16-01-2002 19:39									#1
	The manual Got spare money?

Ok, I'm wondering (once more) as to what format the manual should be in. This regards both the format of the manual and whether it is part of the program rather than a seperate file.

Edit: WTF? It doesn't want to let me post a poll

Ah well, the choices are:

- Text File
- PDF File
- HTML File
- HTML File integrated into the game (ie I write it in HTML and the game has a reader built in)
- Part of the program itself

	16-01-2002 22:35									#2
	Support Apolyton, buy Civilization: The Boardgame

Hi Chris:

I vote for HTML. I think putting a browser into the game is premature, if it'd ever be needed. In addition there would be the online tutorial stuff in the game as discussed in the other thread.

	17-01-2002 20:08									#3
	Support Apolyton, buy GURPS/ Alpha Centauri

I propose both html and a txt version, which is easy to do. PDF is awful - don't even think about it.

	20-01-2002 03:01									#4
	Support Apolyton, buy Alpha Centauri

I vote for a HTML and text version. That way we could ship the text version with the game, and post the HTML version on the site.

John

	20-01-2002 07:30									#5
	Support Apolyton

Yes, HTML and text, in case it needed anymore support.

	20-01-2002 13:28									#6
	Help yourself to an AD-FREE life

I am particularly keen on an online help system. In Java this is best achieved with HTML which can also be viewed, outside of the game, with a browser.

The text version can be straight text, but is probably better in something like Word format. It would be nice if there were some utility to switch between these formats. I am stepping outside my area of knowledge here.

Cheers

	22-01-2002 19:24									#7
	Suffering from ads?

A text version to read outside the game, and some way to give context-sensitive help within the game. No .pdf please.

	22-01-2002 23:08									#8
	Support Apolyton

I vote for an in-game help system and tutorial. People simply don't read manuals.

If you do make a manual, make it html. I hate .pdf files. I really hate them

	23-01-2002 02:05									#9
	Is there ANYBODY who likes PDFs? Inflate your Upload Space

I wonder how does Adobe make money from a so cumbersome file format. Only companies have a reason to use them, because they are not (easily) alterable.

	23-01-2002 04:27									#10
	Re: Is there ANYBODY who likes PDFs? Avatar Enlargement: We've got the solution

quote: Originally posted by axi I wonder how does Adobe make money from a so cumbersome file format. Only companies have a reason to use them, because they are not (easily) alterable.

I've noticed that they are usually scans of existing paper manuals or books. And they do seem to preserve formatting pretty well, unlike most OCR software. So it's probably an issue of ease of use; they have a clerk to scan a manual at minimum wage instead of making a decent html file.

	23-01-2002 07:45									#11
	Support Apolyton or Terrorists Win

I would think that a help system would go well built into the program itself, and HTML allows that while not locking it into "inside the program only".

JavaHelp could eventually be used, but I'm unsure about what it actually takes to make a JavaHelp file. It could be used to build a "Clashopedia"
to handle ingame information, such as unit and terrain stats, technology information, historical info, quick-reference for some game concept information, etc.

The two help systems could easily be handled sepperately, as one would be an actual "Manual" (as in, "How do I play this game?") and the other would be quick access to information when someone asks "What do ports do again..." or "What the heck is a 'Coracle'?" from inside the game itself.

The "Civilopedia" is one of the most pleasant features of later Civ-genre games, and if done simply it would require very little maintenance. Only descriptions and history would ever need to be changed/added, as all stats would automagically be displayed by the game (so rather than writing in the appropriate file "Legions have X attack strength", the Clashopedia would get the attack power of Legions and display it on the appropriate part of the screen).



But speaking in the here-and-now, it should probably first be done in HTML as it seems nearly everyone agrees it should at least be available in that.

If it's needed in more formats they can easily be created at a future date.

Besides, I know for a fact that keeping 2 versions of something updated is at least 2.5X harder than just keeping one updated.

So I would propose that it be kept simple, and until such a time as another format was needed it should be done in either HTML or XML (the former being easiest, the latter being the most robust...but HTML is probably the most wise choice).

	26-01-2002 15:33									#12
	Enter the AD-FREE zone

So far I've written a PHP script that I run on my computer - it reads data textfiles (two for each page - one basic data and the other with the main text) and compiles HTML files. I doing it this way to make it a lot easier for me once there are many pages - I'll hopefully get the first version posted soon.

	26-01-2002 16:37									#13
	Support Apolyton buy from Amazon

Thanks Chris, looking forward to seeing it!

	26-01-2002 19:24									#14
	Support Apolyton, buy Civilization 2

If anyone can come up with a decent name for the help system, that's be great.

	28-01-2002 22:43									#15
	Help yourself to an AD-FREE life

I think the manuals should be written in XML. If we write it in XML the base source of the manual will be available to be read by many formats. Then we can write converters that read the basic file and then outputs in the format we wish for.
F.ex. we could use a php program that Chris talks about to output the manual as HTML.

That would give us the choice to add another format in a later stage if we want to.

Jorgen

	28-01-2002 22:58									#16
	Lose 30 kilos (of popups)

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

What is wrong with HTML?

Cheers

	28-01-2002 23:59									#17
	Enter the AD-FREE zone

'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?

Last edited by colorrr on 29-01-2002 at 00:11

	29-01-2002 00:34									#18
	Suffering from ads?

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

	29-01-2002 14:07									#19
	Increase the size of your Attachments

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

	29-01-2002 17:58									#20
	Support Apolyton, buy Civilization 2

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

	29-01-2002 23:28									#21
	Tired of ads?

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

	30-01-2002 00:28									#22
	Support Apolyton or Terrorists Win

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

	30-01-2002 02:01									#23
	Support Apolyton

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

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

	30-01-2002 03:40									#24
	Support Apolyton buy from Amazon

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.

	30-01-2002 16:34									#25
	Support Apolyton, buy Civilization 2

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.

	30-01-2002 18:30									#26
	Support Apolyton or Terrorists Win

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

	30-01-2002 21:41									#27
	Tired of ads?

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