The manual

[Gary Thomas]

Who is the "we" that is going to write converters?

What is wrong with HTML?

Cheers

[colorrr]

'We' are the group of developers of Clash, is there another 'we' here?

About HTML, as with any other specific advanced formatting language, my opinion is that we should not bind ourselves to using that as the base for the manual text.

My idea is that we write the manual in a basic format in XML that only contains only simple formatting instructions, like f. instance:
<header color="blue" alignment="center">Introduction</header>
<paragraph text_size="small">Welcome to ......</paragraph>.

Then we can do some converters in Java or php or other that read that simple format and output it in a nice, advanced HTML layout for instance.
Later if we find it useful we can write another converter that writes the same data into a text format, or whatever other format we might find useful.
This would also allow the implementation of a similar 'look' of the manual, no matter what the final format is.
We already have an XML reader, would just be a matter of inventing some simple formatting rules and implementing them in a converter class.

What do you other guys think about this?

[LDiCesare]

Gary's point is that our development resources are quite buzy already, so making a format converter is not his or my priority. I'd like to point out that HTML can be xml-compliant (it is, if you use the latest specs), so you get the better of both worlds. You just have to type <br/> instead of <br>
Only the older browsers may not support it...

[Gary Thomas]

Right now that "we" means Laurent, Mark or me. Unless you are volunteering (I hope!)?

There are a great many things that we want to do, and writing an xml converter is not likely to be higher than about 500th on the list, if we can use HTML directly.

Cheers

[colorrr]

Gary and Laurent

It might have gone unnoticed, but I already volunteered to this project, and Mark graciously accepted my help. Just some weeks ago. Since then I have been entering into the discussion here,
reading the models and trying to get the grips of the game.
There is really a lot of things to understand to get into the game in detail.
Recently downloaded the demo v6, and played it a little.
Since I am not sure which part to do yet, you might not have heard much about me.

So I guess now it's official. You have got yourself a new crewmember. My name is Jorgen Vasshaug, more info can be found at :

my technical profile

Yours is a truly interesting game, glad to be part of it!

Jorgen

[Gary Thomas]

That is really great! (I see you are pretty good at Spanish - what platform does that run on?)

I have been hugely keen on an online help system from the beginning, but it has never had very high priority. It might be the very area for you to work in, since it is close to your interests.

There is a book on Java help (which I have, unfortunately at home, which I will not be visiting until March). It would be nice if the work could be coordinated with that book, so others can relate to it. Also, we will need to make sure that everyone is agreed on the direction of development, so we need pretty constant feedback, probably through the forum.

My preference, not necessarily shared by others, is to have the on-line help the substantive reference, but available off-line, with a printable version as the manual.

I certainly don't want what happens in Civ, where you have to hunt around a number of sources for help, and sometimes it just isn't available. I think, with your input, we can show the Civ people how to do it!

I rather feel that the time has come to start a Help (rather than a Manual) thread.

A caution - this is no reflection on you, but we have had a large number of people say that they will help with the coding, then nothing happens.

Cheers

[Mark_Everson]

That's a great idea, since there seems to be a consensus for online help. And I would Love to stop hearing people whining about it

Jorgen, how does that grab you? It would fit your desires in that its something that can be started from scratch. Although it is a big area, it can start small. And the coding itself, as opposed to hooking up the entries, should be reasonably compact. (Though I may be showing my ignorance here.) You don't need to decide right away, but please think about it, and let us know what you decide.

-Mark

[colorrr]

Originally posted by Gary Thomas
That is really great! (I see you are pretty good at Spanish - what platform does that run on?)

I am not sure I understand your question. It sounds like you think Spanish is a programming language :-)

A caution - this is no reflection on you, but we have had a large number of people say that they will help with the coding, then nothing happens.

Ah, yes. Mark mentioned that. Of course I can tell you that is not my intentions, but I guess you heard that one too before.
Time will prove to you that I am serious about contributing.

As for doing an on-line help, I guess that would be ok to start with.
Since client/server stuff is what I do everyday, I was wanting to do something different.
Most of all I am looking for experience with game programming in Java.
But anyway, doing a help system would let me know the game better, and later I can get into some other areas as well, as for instance the map generator (trying to make a deal here . . . ;-)
If you provide help in writing some sections of the help text, I could take charge of the other stuff.

I suggest we open that other thread and continue the help discussions there.

Color

[Chris Wilkinson]

There's no point in having a seperate manual and on-line help system...I've written quite a bit of stuff so far, so I could get it converted into xml or .txt or whatever, along with my html version, so it could be read by the on-line system.

[Mark_Everson]

Color:

Sounds like a good compromise to me. You can provide clear value to the team in an area you're familiar with, and then branch out into the things you really want to do... But if you think the help thing would be Too much like work its probably not a good idea. Only you can make the best guess if doing the help will burn you out prematurely on Clash coding or not! Potentially once the help gets going you should be able to that and something else in parallel anyway. Map generation sounds ok to me. Lets see what Gary thinks.

Chris:

I don't Think anyone is suggesting the manual and help system be completely distinct... Is anyone? I think the suggestion for a separate thread is to discuss issues with the help system that are unique to it versus the manual. And there will be many. Lots of coding issues, and GUI issues.

At least as far as I can see it the online help would, as you say, consist mostly of manual snippets. And the online help should provide links to the manual online. I personally would rather read a few pages of manual rather than bop around and click-and-read many disjointed little blurbs. The only time I really like the online help stuff is when there's a small feature I don't know or don't remember. But everyone works differently, and I think I'm in the minority here.

[colorrr]

Mark:

It is not the coding part that worries me, it's the part writing the text for the help about a part of the system I do not know. That's where I was asking for the help of the rest of the team to write that text.

Everyone:

I opened another thread on the on-line help system:

The on-line help system

Check this thread for dicussions about the source for the help and manual systems.

Jorgen

[Gary Thomas]

As I understand the division of responsibilities, Chris is responsible for the manual and help text, and Jorgen is responsible for incorporating this text into an on-line help system.

I would very much like to see the on-line help and manual integrated as much as possible. Unfortunately I am in a situation where web access is not as easy as I would like. This situation will continue until March 2, when I go home. This means that my conttribution is going to be a bit constrained until then.

Jorgen, the actual code is going through a bit of a traumatic upheaval at the moment, but a clean version should be available within a few days. The help system will be initially available through a help button on the control bar. Later, context sensitive help would be nice.

Cheers