Manual

[Kroc]

Quality documentation is a must. One of the issues with Elite-A/B is that, whilst they add much to the game, the documentation just assumes you're experienced with Elite and only lists what's added in a hodge-podge way rather than preparing new players. My intention is for Elite DX to be fully accessible to players who have a.) never played Elite before, and b.) never played a C64 or other 8-bit game before.

For those who don't read manuals, and because you may not even have the possibility to read the manual and play the game on the device you're using (e.g. PSP), not least that it's a right pain switching back and forth between game and manual, I plan to include an in-game manual (#10) possibly as a pre-game docs program as is common in the C64 cracking scene these days.

This issue however is for an external manual. One key consideration is that the manual will have to change contents depending on compile-time options so we'll need some kind of simple ifdef script to include different chunks as we go. To begin with a .txt file will suffice for a manual, but in the future a more complete build system that can output HTML / PDF / eBook would be nice.

See #10: built in encyclopedia / manual, #15: on screen controls

[gitjeff2]

@Kroc what about leveraging pandoc or possibly XeTeX? Do you anticipate the manual being in English only, or do you expect translations?

I'm open to writing something for the English edition of the text.

While I'm on the subject of translation...

I've poked around at Elite Harmless' code base a bit. I see you've separated your text strings into their own files. I know the text uses a tokenized strings as a means to compress the in-game text. (That was a very common trick back in the day for text heavy games.) Are you open to having this code modernized to make it more efficient and possibly support languages other than English?

[Kroc]

I am planning to rip out the entire text tokenisation and replace it with something better that isn't so densely self-referential. One of the major problems is that the exact order and number of letter pairs -- and the fact that the two pairs tables overlap!! -- are required for the string generation, such as planet names & descriptions. The tokens = code format is so deeply ingrained that I still haven't reversed and documented it all, so any attempt at modernisation would be up against quite some thorny code. Translation I think is out of the question until the code has been cleanly separated from the text itself.

You're welcome to attack it, but you'll need to remember that any changes you make must always retain the [output of the] original code. This is done by conditional compile directives .ifdef & .ifndef OPTION_ORIGINAL , or by moving original code to its own file in "/src/orig".

Lastly, make sure you take a fork off of the "Kroc" branch as that's the most up to date branch.

[gitjeff2]

@Kroc Yikes! That sounds like a lot of pain. Maybe I should stick to my original idea of writing a manual. Is Pandoc okay on that front?

[Kroc]

I've not used Pandoc, but I know that it is commonly used to produce text manuals of various formats, so I am okay with that! If you could modify the "setup.sh" script to include Pandoc in the installation, and include manual generation in the build script ("build.sh"), that would be great, but if you are uncertain how to do these things, I'm happy to do that for you once you've got a starting foothold (i.e. use the "docs" directory, the file already in there can be moved elsewhere if you want)

[gitjeff2]

I've not used Pandoc, but I know that it is commonly used to produce text manuals of various formats, so I am okay with that!

Cool. I forked this repository and created a game-manual branch. I'll update you when I have something worth mentioning.

If you could modify the "setup.sh" script to include Pandoc in the installation...

Yep, sure, when I get that far I'll update the setup and build scripts. Just out of curiosity, is there a reason you didn't go with a Makefile to manage all of this instead?

[Kroc]

Only because nobody should ever suffer through trying to understand makefiles. Maybe in the future when the project has reached some of its goals, but right now a makefile would just hinder people being able to jump in and learn / understand the project :)