The manual

[Chris Wilkinson]

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

[Mark_Everson]

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.

[axi]

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

[Dominic]

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

[Mikael]

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

[Gary Thomas]

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

[Simon Loverix]

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

[Richard Bruns]

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

[axi]

Is there ANYBODY who likes PDFs?

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.

[Richard Bruns]

Re: Is there ANYBODY who likes PDFs?

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.

[Plutarck]

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

[Chris Wilkinson]

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.

[Mark_Everson]

Thanks Chris, looking forward to seeing it!

[Chris Wilkinson]

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

[colorrr]

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