30-01-2002 18:26									#1
	The On-line help system Support Apolyton, buy Civilization: The Boardgame

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?

	31-01-2002 05:38									#2
	Re: The On-line help system Support Apolyton, buy Civilization 2

Thanks for taking this on Jorgen!

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

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

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

quote: 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!

	31-01-2002 10:53									#3
	Enter the AD-FREE zone

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

	31-01-2002 14:59									#4
	Browse Apolyton AD-FREE

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.

	01-02-2002 01:03									#5
	Support Apolyton

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

	05-02-2002 07:01									#6
	Support Apolyton

quote: 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?

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

	05-02-2002 12:56									#7
	Suffering from ads?

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

	06-02-2002 01:49									#8
	Enter the AD-FREE zone

And I definitely agree.

	06-02-2002 02:28									#9
	Full PM-box? Change here!

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

	19-03-2002 22:59									#10
	Got spare money?

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 :

1. A predefined constant identifying the desired help item
   
2. An object contaning the necessary information to reference the help information
   
3. The object that is the focus of the help request (the calling class?).
   

	20-03-2002 02:39									#11
	Support Apolyton, buy Civilization: The Boardgame

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

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

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

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

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

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

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

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

quote: Opening up an external browser client with the html help page

A possibility, but probably slow and ugly.

quote: Showing the html page inside the client itself

I prefer this option.

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

I agree.

quote: 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

	20-03-2002 19:05									#12
	Get a bigger avatar today!

Thanks for responing in such detail Gary.

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

quote: > 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

	21-03-2002 01:35									#13
	Support Apolyton, buy Civilization 2

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

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

quote: 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

	21-03-2002 21:29									#14
	Support Apolyton, buy GURPS/ Alpha Centauri

quote: 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?

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

quote: 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

	22-03-2002 03:08									#15
	Support Apolyton, pre-order Civilization IV

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

quote: 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

	22-03-2002 18:02									#16
	Support Apolyton, pre-order Civilization IV

Since the actual activation of the help system (call to the static 'help server' method) has to be programmed by whoever is doing the interface, that means you are pretty much free to define the activation action that has to be taken by the user.
If you press F1, it would trigger among others the KeyPressed event, passing an EventObject (KeyEvent inherits this one) as a parameter. With that object you are able to access the source component of that event.

All the events that are key driven or mouse driven has a source object that you can pass to the help system.

For the key events this would be the component that has the focus in the moment. For the mouse events it would be the component under the cursor at the moment of the event.
Check out these events as they carry some more information that is useful.

That seems like a good way to make context sensitive help.

To be honest I did not check out the Java Help system. I think the big download (20+ MB ??) stalled me the last time I tried.

I'll have to make the effort someday.


Color

	23-03-2002 08:22									#17
	Browse Apolyton AD-FREE

My point in asking about the interface is that having the game code components implement an interface implies that the help system will make a call on some object method defined in the interface. Since the help display is initiated by the component, it seems to me that it is the help system which should be implementing an interface, called by the component, and passing the help identifier as a parameter.

Cheers

	23-03-2002 09:08									#18
	Remove this text

Sure, if you prefer to call a method and pass the help identifier this is fine with me. How you get hold of that identifier would then be up to you. You could store a new variable in each class and then when someone invokes the help you have to check that the object that has the focus of the help has this variable, get hold of the value and pass it on, or do it in another way.
This would basically mean going back to the first option envisioned to pass information. The identifier of the help item could be stored as a String in each class or in another constant value container class to organize all the identifiers (making sure there are no duplicates).

The reasoning behind the calling objects implementing a java interface (not a class), was to make the code easier for the caller:
upon receiving the help request event, he would just pass on the object that is the focus of the help, and not worry if the object has any help attached and to fetch the identifier in order to pass it. Passing the object means the help system would then check if the object implements help and fetch the necessary information.
The process would be automatic.
Upon creating an instance of the source object the help identification data would be filled out.
I think this is the better solution. If you have to touch the class to add a help identifier variable, you might as well implement an extra interface to smoothen the help execution code.

You choose the way that serves you best.

	24-03-2002 03:03									#19
	Browse Apolyton AD-FREE

I see what you meant now.

Unfortunately, in many cases, the help "object" will just be an image drawn on a panel, a picture of a unit, for example. Such an "object" will actually be an area of the panel, rather than a real object. This is also true of the map. The only object available is the mouse event, which does give the coordinates, but doesn't tell you what is actually there, and hence what type of help is required.

It would be possible to make sure that every distinct area of the map has an associated object, implementing the interface, and return that object. It is just that that is not the way it works now.

On the other hand, with a keen and experienced gui writing team, fixing that should be no problem.

I do prefer your system as leading to greater encapsulation.

Cheers

	27-03-2002 19:51									#20
	Support Apolyton or Terrorists Win

quote: Originally posted by Gary Thomas Unfortunately, in many cases, the help "object" will just be an image drawn on a panel, a picture of a unit, for example. Such an "object" will actually be an area of the panel, rather than a real object. This is also true of the map. The only object available is the mouse event, which does give the coordinates, but doesn't tell you what is actually there, and hence what type of help is required. It would be possible to make sure that every distinct area of the map has an associated object, implementing the interface, and return that object. It is just that that is not the way it works now.

I think the the mouse event has a source object too. That would have to be confirmed.
And if not, I think there is a method somewhere (maybe the SwingUtilities class) that returns the current object visible at the (mouse) coordinates. Of course if it happens to be a click on a map/image this would return the panel, and not the map square.
This panel could have routine, taken some input coordinates, to calculate and return the current hex information as an object.

I am pretty sure all these problems can be fixed, so that it could always be possible to pass an object of some kind.

quote: On the other hand, with a keen and experienced gui writing team, fixing that should be no problem. I do prefer your system as leading to greater encapsulation.

It get the impression a interface overhaul is on the wishlist.
It seems to me it could be good to discuss more (Oh no! More discussion! :-) how that interface should be before deciding exactly how to incorporate the help into this.

What we could do with the help system is implement the two ways of accessing the system: with an object implementing the help interface or just passing a string paramater.
That way, the help interface should be useable in the existing and a possible new GUI.

Maybe I could look more into the GUI as well, if there is no one doing this work at this time. I find the subject interesting.
I have been playing with the idea of making a full screen interface to clash. . . . any opinions?

Jorgen

	27-03-2002 21:57									#21
	Support Apolyton, buy Civilization 2

I forgot we already had an GUI thread so the last phrase is irrelevant, is was written before I read the other thread.