Merge lp:~widelands-dev/widelands/reworked-readme into lp:widelands

[Hans Joachim Desserud]

(Read: request for feedback, not request for merge)

I briefly started with reworking the readme. So far I've thrown it into the first dialog for the atlantean mission, and tweaked it a bit to see how it works. (This will of course be reverted once we have a final version and support for displaying it from the main menu.)

The text itself is untouched, as I figuered it made more sense to get the format down properly, then start rewriting as it will be presented how it will end up.

For now, I would mainly like some replies to the quetions posted in the comments, though general feedback is also welcome.

Work in progress-disclaimer applies. ;)

[SirVer (sirver)]

- TOOD: I haven't converted all of this section, but I'm not sure how good it
Noone forces you to have all in the paragraph translated. You can do things like p(_"text" .. "<br>" .. _"more text").

-- How to deal with parts which want specific styles (like centered/italics) and still be translatable?
See https://wl.widelands.org/docs/wl/autogen_aux_formatting/#p. You can pass the options for p as first argument: p("font-size=14 font-style=italic text-align=center", _"translated text"). This should work theoretically. :)

-- TODO: Btw, looks like neither spaces, tabs nor \t provides whitespace.
This is a bug in the old renderer. The new one does support tables and as soon as we use it we can reformat this to look nicer.

[Hans Joachim Desserud (hjd)]

>Noone forces you to have all in the paragraph translated.
Thanks for the tip. :)

>-- TODO: Btw, looks like neither spaces, tabs nor \t provides whitespace.
>This is a bug in the old renderer.
I thought we were using the new one for campaign dialogs now?

I've now converted the format of the general readme. Haven't had time to start the rewrite yet, but I have some ideas for it at least.

[SirVer (sirver)]

> >-- TODO: Btw, looks like neither spaces, tabs nor \t provides whitespace.
> >This is a bug in the old renderer.
> I thought we were using the new one for campaign dialogs now?
Unfortunately not yet :(. The new renderer is only used in a few places right now, mostly in the UI. Theres is a branch that uses the new renderer for everything, but we are not yet ready for merge.

[SirVer (sirver)]

I'll set this to in progress, feel free to change if you think this is not the correct state.

[SirVer (sirver)]

I merged this now in a way - I started from your atlantean modification, added the code to deal with Lua files when showing readmes and finished your conversion to be a 1to1. I am going ahead and rewriting parts of the README now that are outdate or look funky. Thanks for your work on this, it made this task significantly quicker for me.

=== modified file 'campaigns/atl01.wmf/scripting/texts.lua'
--- campaigns/atl01.wmf/scripting/texts.lua	2012-12-16 19:08:16 +0000
+++ campaigns/atl01.wmf/scripting/texts.lua	2013-09-01 19:07:32 +0000
@@ -155,20 +155,79 @@
 {
    title = _ "Proudest to the death",
    body = rt(
-      h1(_"Favored by the god") ..
-      p(_
-[[On the hidden and lost island of Atlantis, a proud tribe settled since the
-world was very young. Ruled by the bloodline of King Ajanthul - the first human
-to be empowered by the sea god Lutas to breathe above the sea level - and the
-wise clerics, who provided the link to Lutas - they prospered and became
-civilized.]]
-      ) .. p(_
-[[This story happens during the regency of King Askandor, the 43rd successor of
-King Ajanthul. He has been a good king, ruling Atlantis with wisdom and
-foresight. But with age, he became afraid of dying and so he began looking for
-a cure to death even though most clerics warned him. Some said, endless life
-was only for the gods and to seek for it was forbidden.]]
-      )
+      h1(_"README")
+ -- TODO: add the logo image somehow. Can probably look at how portraits are added and do something similar.
+.. p(
+[[<rt image=pics/wl-logo-64.png image-align=center text-align=center></rt>]])
+ -- TODO: Investigate whether I really need to use rt here. text-align didn't seem to be applied to the paragraphs
+.. p("<rt text-align=center>") .. p("font-size=38 font-face=Widelands/Widelands font-color=#2F9131", "Widelands")
+.. p("font-size=14 font-style=italic text-align=center", _"an open source strategy game")
+.. p("</rt><rt>")
+
+.. h2(_"Introduction")
+.. p(_
+[[Widelands is a strategy game aiming for gameplay similar to Settlers II by BlueByte.<br>In this game, you start out on a small piece of land with just a few resources. Using these, you'll create an empire with many thousands of inhabitants. On your way towards this goal, you will have to establish an economic infrastructure, explore the lands around you and face enemies who are trying to rule the world just like you.]]) 
+.. h3(_"Check out the Widelands project homepage:") 
+.. p("http://wl.widelands.org")
+.. p(_"Widelands is licensed under the GNU General Public License (GPL). For more information, see the file 'COPYING' or select the License button from the main menu.")
+.. h3(_"Status")
+.. p(_
+[[Widelands is now on the step of being playable, but to become more playable volunteers are needed. Your contributions (yes, I'm talking to you) are required, especially in the area of graphics, to make Widelands a better game.]])
+.. h2(_"General game control") 
+.. p(_"To close an open window, right click it.")
+.. p(_"To minimize/maximize a window, click on the titlebar of that window either with middle mousebutton or with left mousebutton while holding down CTRL.")
+.. h2(_"Keyboard shortcuts (in-game)")
+.. p(_"SPACE toggles build-help" .. "<br>"
+.. _"M toggles minimap" .. "<br>"
+.. _"N toggles messages ('news')" .. "<br>"
+.. _"C toggles census" .. "<br>"
+.. _"S toggles statistics" .. "<br>"
+.. _"I toggles stock inventory" .. "<br>"
+.. _"O toggles objectives" .. "<br>"
+.. _"F toggles fullscreen" .. "<br>"
+.. _"Home centers main mapview on starting location" .. "<br>"
+.. _"(CTRL+) 0-9  Remember and go to previously remembered locations" .. "<br>"
+.. _", goes to previous location" .. "<br>"
+.. _". goes to next location" .. "<br>"
+.. _"PAGEUP         increases gamespeed" .. "<br>"
+.. _"PAGEDOWN    decreases gamespeed" .. "<br>"
+.. _"PAUSE         pauses the game (only for local games)" .. "<br>"
+.. _"F6           shows the debug console (only in debug-builds)" .. "<br>"
+.. _"Ctrl+F10    quits the game immediately" .. "<br>"
+.. _"F11         takes a screenshot")
+.. p(_"When finishing a road, flags will be placed along it if Ctrl is held down. Default is to place flags from end to start. If Shift is also held down, they are placed from start to end instead.")
+.. p(_"When removing a road, if Ctrl is pressed all flags up to the first junction are removed.")
+.. p(_"In the message window, the following additional shortcuts are available:")
+.. p(_"G           goes to location corresponding to current message" .. "<br>"
+.. _"DELETE      archives the current message")
+.. h2(_"Online Help")
+.. p(_"If you need documentation or help for Widelands or the Widelands Editor, be sure to visit our homepage. You can find an up to date online help at:")
+.. p("http://wl.widelands.org/wiki/")
+.. h2(_"Reporting Bugs")
+
+-- TODO: should we still mention the mailing list at the end as a backup for people who don't wish to register at Launchpad?
+-- Sending an email somewhere might be considered a smaller "investment" than registering at a site.
+.. p(_"If you encounter a bug, please report it to our bugtracker:")
+.. p("https://bugs.launchpad.net/widelands")
+.. p(_"Please provide enough background information. Tell us:")
+.. p(_"- Detailed steps on how to trigger the bug, if possible.")
+.. p(_"- What you expected to happen when performing the steps and what actually happened.")
+.. p(_"- Which version of Widelands you are running (i.e. either the build number or the revision number if you are running the development release)")
+.. p(_"- Please also include which operating system you are running Widelands on, as some bugs can be platform specific.")
+.. p(_"- Which map you were playing when the bug occured.")
+.. p(_"- If the bug concerns something not being displayed correctly or if it helps demonstrate the issue, please include one or more screenshots.")
+.. p(_"- If you have a save game or replay demonstrating the issue (for instance crashes where it can be hard to tell exactly what is triggering it), please include that too. For more information, see the section on Replays below.")
+.. p(_"- send us a compressed (zip, gzip, bzip2) session record if possible, unless the<br>bug is trivial to reproduce. In fact, it may be a good idea to always record<br>your sessions in case a bug surfaces. For more explanation, see below.")
+.. h2(_"Replays")
+.. p(_"Widelands records every game you play in two files. One of these files has a .wrpl.wgf extension and contains an initial savegame. The other file has just a .wrpl extension and contains all commands that were issued by all players, such as building a road or attacking an enemy. The rest of the filenames will tell you the time you started the game.")
+.. p(_"Using the Watch Replay option in the main menu, a previously played game will be precisely reconstructed for you to watch. Note, however, that even small changes in the game data files or the Widelands executable can cause a replay to become incompatible and to 'go out of sync'. This is similar to how network games will suffer from desynchronization problems if one of the players has a different version of the game.")
+.. p(_"Replays are a very useful tool to find bugs in the game logic code, so we ask you to attach replay files to all bug reports that you submit. The replay files are saved in the ~/.widelands/replays directory in your home on Linux and in the replays subdirectory of your Widelands installation on Windows.")
+.. h2(_"Creating a Session Record")
+.. p(_"Widelands can record all your keypresses and mouse movements to a file. It can then replay an entire session from starting the game to exiting it. This is really helpful for debugging problems.")
+.. p(_"To create a session record, start the game with the --record parameter. On Linux, simply start Widelands like so: $ ./widelands --record=filename.rec")
+.. p(_"On Windows, create a shortcut to the file widelands.exe (right-click on widelands.exe and choose Create Shortcut). Then edit the shortcut (right-click on the newly created shortcut and choose Properties). The Target field should read something like c:\games\widelands\widelands.exe. Change this to c:\games\widelands\widelands.exe --record=filename.rec.")
+.. p(_"A binary file called filename.rec will be created. To play it back, perform the same steps as outlined above, but replace --record with --playback.")
+.. p(_"Note that while recorded files are platform independent, they generally won't work across different versions of Widelands, because the user interface and the order in which low-level functions can be called may change between versions. Session records are not intended to serve as demo files; they are mostly a debugging tool which helps us to track down bugs.")
    ),
 },
 {