Mercurial > hg > openttd

changeset 17086:7986f89e6d4b draft

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
(svn r21823) -Documentation: update the style used in several documentation files
author smatz <smatz@openttd.org>
date Sun, 16 Jan 2011 13:36:47 +0000
parents f26dc3f0163d
children 4ce82f272b97
files docs/32bpp.txt docs/HOWTO_compile_lang_files.txt docs/admin_network.txt docs/multiplayer.txt known-bugs.txt readme.txt
diffstat 6 files changed, 157 insertions(+), 143 deletions(-) [+]
line wrap: on
line diff
--- a/docs/32bpp.txt
+++ b/docs/32bpp.txt
@@ -1,15 +1,24 @@
 32bpp and OpenTTD
-=================
+Last updated:    2007-06-13
+------------------------------------------------------------------------
+
 
+Table of contents
+-----------------
+1.0) About
+2.0) The format
+
+
+1.0) About
+---- -----
 OpenTTD has 32bpp support. This means: OpenTTD still is 8bpp, but it has the
 posibility to override the graphics with 32bpp. This means that it isn't a
 replacement of grf or newgrf, but simply an addition. If you want to use 32bpp
 graphics of a newgrf, you do need the newgrf itself too (with 8bpp graphics).
 
 
-The Format
-----------
-
+2.0) The format
+---- ----------
 32bpp images are stored in PNG. They should go in:
   data/sprites/<grfname>/<SpriteID>.png
 
@@ -33,4 +42,3 @@
 chunks upon save, so you have to readd it every time you save your image.
 
 Your images should be the same as the grf, in size.
-
--- a/docs/HOWTO_compile_lang_files.txt
+++ b/docs/HOWTO_compile_lang_files.txt
@@ -1,5 +1,17 @@
-STRGEN USAGE
-------------
+OpenTTD and strgen
+Last updated:    2009-06-30
+------------------------------------------------------------------------
+
+
+Table of contents
+-----------------
+1.0) strgen usage
+ * 1.1) Examples
+ * 1.2) strgen command switches
+
+
+1.0) strgen usage
+---- ------------
 This guide is only interesting for people who want to alter something
 themselves without access to translator.openttd.org. Please note that
 your compiled language file will only be compatible with the OpenTTD version
@@ -14,8 +26,8 @@
 it to be used inside OpenTTD. strgen needs the master language file
 english.txt to work. Below are some examples of strgen usage.
 
-EXAMPLES
---------
+1.1) Examples
+---- --------
 Example 1:
 if you are in the root of your working copy (svn code), you should type
 strgen/strgen -s lang lang/english.txt
@@ -35,8 +47,8 @@
 You can interchange english.txt to whichever language you want to generate a
 .lng file for.
 
-STRGEN COMMAND SWITCHES
------------------------
+1.2) strgen command switches
+---- -----------------------
 -v | --version
 strgen will tell what svn revision it was last modified
 
--- a/docs/admin_network.txt
+++ b/docs/admin_network.txt
@@ -1,19 +1,23 @@
-Admin Network
-
-   Preface
-1. Joining the network
-2. Asking for updates
-3. Polling manually
-4. Sending rcon commands
-5. Sending chat
-6. Receiving chat
-7. Disconnecting
-8. Certain packet information
+OpenTTD's admin network
+Last updated:    2010-12-30
+------------------------------------------------------------------------
 
 
-   Preface
-----------
+Table of contents
+-----------------
+1.0) Preface
+2.0) Joining the network
+3.0) Asking for updates
+ * 3.1) Polling manually
+4.0) Sending rcon commands
+5.0) Sending chat
+ * 5.1) Receiving chat
+6.0) Disconnecting
+7.0) Certain packet information
 
+
+1.0) Preface
+---- -------
   The admin network provides a dedicated network protocol designed for other
   applications to communicate with OpenTTD. Connected applications can execute
   console commands remotely (rcon commands) with no further authentication.
@@ -33,12 +37,11 @@
   removed from packets in later versions, except the possibility that complete
   packets are dropped in favour of a new packet.
   This though will be reflected in the protocol version as announced in the
-  ADMIN_PACKET_SERVER_PROTOCOL in section 1.
+  ADMIN_PACKET_SERVER_PROTOCOL in section 2.0).
 
 
-1. Joining the network
-----------------------
-
+2.0) Joining the network
+---- -------------------
   Create a TCP connection to the server on port 3977. The application is
   expected to authenticate within 10 seconds.
 
@@ -68,9 +71,8 @@
   However, ADMIN_PACKET_SERVER_WELCOME only after a ADMIN_PACKET_SERVER_NEWGAME
 
 
-2. Asking for updates
----------------------
-
+3.0) Asking for updates
+---- ------------------
   Asking for updates is done with ADMIN_PACKET_ADMIN_UPDATE_FREQUENCY.
   With this packet you define which update you wish to receive at which
   frequency.
@@ -116,9 +118,8 @@
   ADMIN_UPDATE_CMD_LOGGING results in the server sending:
     - ADMIN_PACKET_SERVER_CMD_LOGGING
 
-3. Polling manually
--------------------
-
+3.1) Polling manually
+---- ----------------
   Certain AdminUpdateTypes can also be polled:
     - ADMIN_UPDATE_DATE
     - ADMIN_UPDATE_CLIENT_INFO
@@ -138,9 +139,8 @@
   Additional debug information can be found with a debug level of net=3.
 
 
-4. Sending rcon commands
-------------------------
-
+4.0) Sending rcon commands
+---- ---------------------
   Rcon runs separate from the ADMIN_UPDATE_CONSOLE AdminUpdateType. Requesting
   the execution of a remote console command is done with the packet
   ADMIN_PACKET_ADMIN_RCON.
@@ -158,9 +158,8 @@
   was not sent from the admin network.
 
 
-5. Sending Chat
----------------
-
+5.0) Sending chat
+---- ------------
   Sending a ADMIN_PACKET_ADMIN_CHAT results in chat originating from the server.
 
   Currently four types of chat are supported:
@@ -173,10 +172,8 @@
   using the respective DestType and ID.
   This is a message prefixed with the 3 stars, e.g. *** foo has joined the game
 
-
-6. Receiving chat
------------------
-
+5.1) Receiving chat
+---- -------------
   Register ADMIN_UPDATE_CHAT at ADMIN_FREQUENCY_AUTOMATIC to receive chat.
   The application will be able to receive all chat the server can see.
 
@@ -184,16 +181,14 @@
   private chat for to the server is distributed into the admin network.
 
 
-7. Disconnecting
-----------------
-
+6.0) Disconnecting
+---- -------------
   It is a kind thing to say good bye before leaving. Do this by sending the
   ADMIN_PACKET_ADMIN_QUIT packet.
 
 
-8. Certain packet information
------------------------------
-
+7.0) Certain packet information
+---- --------------------------
   All ADMIN_PACKET_SERVER_* packets have an enum value greater 100.
 
   ADMIN_PACKET_SERVER_WELCOME
@@ -211,4 +206,3 @@
     treated as such. Do not rely on IDs or names to be constant
     across different versions / revisions of OpenTTD.
     Data provided in this packet is for logging purposes only.
-
--- a/docs/multiplayer.txt
+++ b/docs/multiplayer.txt
@@ -1,9 +1,21 @@
-Multiplayer Manual for OpenTTD
-==============================
+Multiplayer manual for OpenTTD
+Last updated:    2010-11-30
+------------------------------------------------------------------------
+
 
-1. Starting a Server
----------------------
+Table of contents
+-----------------
+1.0) Starting a server
+2.0) Connecting to a server
+ * 2.1) Connecting to a server over the console
+3.0) Playing internet games
+4.0) Tips for servers
+5.0) Some useful things
+6.0) Troubleshooting
 
+
+1.0) Starting a server
+---- -----------------
  - Click "multiplayer" on the startup screen
  - Click "start server"
  - Type in a game name
@@ -14,9 +26,8 @@
  - Start playing
 
 
-2. Connecting to a Server
---------------------------
-
+2.0) Connecting to a server
+---- ----------------------
  - Click "multiplayer" on the startup screen
 
  - If you want to connect to any network game in your LAN click on 'LAN', then
@@ -43,17 +54,14 @@
 
  - Happy playing
 
-
-3. Connecting to a Server over the Console
--------------------------------------------
-
+2.1) Connecting to a server over the console
+---- ---------------------------------------
  - Open the console and type in the following command:
     connect <ip/host>:<port>#<company-no>
 
 
-4. Playing Internet-Games
---------------------------
-
+3.0) Playing internet games
+---- ----------------------
  - Servers with a red dot behind it have a different version then you have. You
    will not be able to join those servers.
 
@@ -83,9 +91,8 @@
    NB: changing frame_freq has more effect on the bandwidth then sync_freq.
 
 
-5. Tips for servers
---------------------
-
+4.0) Tips for servers
+---- ----------------
  - You can launch a dedicated server by adding -D as parameter.
  - In UNIX like systems, you can fork your dedicated server by adding -f as
    parameter.
@@ -142,9 +149,8 @@
        #max_clients * #max_clients * bytes_per_frame * 10 KiB.
 
 
-6. Some useful things
-----------------------
-
+5.0) Some useful things
+---- ------------------
  - You can protect your company so nobody else can join uninvited. To do this,
    set a password in your Company Screen
 
@@ -156,9 +162,8 @@
  - Servers can now kick players, so don't make them use it!
 
 
-7. Troubleshooting
-------------------
-
+6.0) Troubleshooting
+---- ---------------
  - My advertising server does not show up in list at servers.openttd.org
      Run openttd with the '-d net=2' parameter, as this will show whether it
      receives replies from the master server. If it does not receive replies it
--- a/known-bugs.txt
+++ b/known-bugs.txt
@@ -1,18 +1,18 @@
 OpenTTD's known bugs
-Last updated:    2010-01-09
+Last updated:    2011-01-09
 Release version: 1.1.0-beta3
 ------------------------------------------------------------------------
 
 
-Table of Contents:
-------------------
-1) About
-2) Known bugs in this release
-3) Known bugs that will not be solved
+Table of contents
+-----------------
+1.0) About
+2.0) Known bugs in this release
+ * 2.1) Known bugs that will not be solved
 
 
-1) About:
--- ------
+1.0) About
+---- -----
 All bugs listed below are marked as known. Please do not submit any bugs
 that are the same as these. If you do, do not act surprised, because
 we WILL flame you!!
@@ -22,8 +22,8 @@
 by the number below on http://bugs.openttd.org.
 
 
-2) Known bugs in this release:
--- ---------------------------
+2.0) Known bugs in this release
+---- --------------------------
 The following bugs are known to exist in this release and we intend to
 fix them. Some bugs are known but are not fixable or fixing them would
 cause further problems. Those bugs can be found in the "Known bugs that
@@ -43,9 +43,8 @@
 - 3447	[OSX] SDL port is unuseable
 - 2484	[OSX] Cannot enter CJK characters
 
-
-3) Known bugs that will not be solved:
--- -----------------------------------
+2.1) Known bugs that will not be solved
+---- ----------------------------------
 This section lists all known bugs that we do not intend to fix and the
 reasons why we think that fixing them is infeasible. We might make some
 minor improvements that reduce the scope of these bugs, but we will not
--- a/readme.txt
+++ b/readme.txt
@@ -1,34 +1,35 @@
-OpenTTD README
+OpenTTD readme
 Last updated:    2011-01-09
 Release version: 1.1.0-beta3
 ------------------------------------------------------------------------
 
 
-Table of Contents:
-------------------
+Table of contents
+-----------------
 1.0) About
 2.0) Contacting
- * 2.1 Reporting Bugs
- * 2.2 Reporting Desyncs
-3.0) Supported Platforms
+ * 2.1) Reporting bugs
+ * 2.2) Reporting desyncs
+3.0) Supported platforms
 4.0) Installing and running OpenTTD
- * 4.1 (Required) 3rd party files
- * 4.2 OpenTTD directories
- * 4.3 Portable Installations (External Media)
+ * 4.1) (Required) 3rd party files
+ * 4.2) OpenTTD directories
+ * 4.3) Portable installations (portable media)
 5.0) OpenTTD features
-6.0) Configuration File
+ * 5.1) Logging of potentially dangerous actions
+6.0) Configuration file
 7.0) Compiling
  * 7.1) Required/optional libraries
  * 7.2) Supported compilers
 8.0) Translating
- * 8.1 Translation
- * 8.2 Previewing
+ * 8.1) Translation
+ * 8.2) Previewing
 9.0) Troubleshooting
 X.X) Credits
 
 
-1.0) About:
----- ------
+1.0) About
+---- -----
 OpenTTD is a transport simulation game based upon the popular game Transport
 Tycoon Deluxe, written by Chris Sawyer. It attempts to mimic the original
 game as closely as possible while extending it with new features.
@@ -36,7 +37,8 @@
 OpenTTD is licensed under the GNU General Public License version 2.0. For
 more information, see the file 'COPYING'.
 
-2.0) Contacting:
+
+2.0) Contacting
 ---- ----------
 The easiest way to contact the OpenTTD team is by submitting bug reports or
 posting comments in our forums. You can also chat with us on IRC (#openttd
@@ -47,9 +49,8 @@
 You can also find the OpenTTD forums at
 http://forum.openttd.org/
 
-
-2.1) Reporting Bugs:
----- ---------------
+2.1) Reporting bugs
+---- --------------
 First of all, check whether the bug is not already known. Do this by looking
 through the file called 'known-bugs.txt' which is distributed with OpenTTD
 like this readme.
@@ -87,8 +88,8 @@
  * Attach crash.dmp, crash.log and crash.sav. These files are usually created
    next to your openttd.cfg. The crash handler will tell you the location.
 
-2.2) Reporting Desyncs:
----- ------------------
+2.2) Reporting desyncs
+---- -----------------
 As desyncs are hard to make reproducible OpenTTD has the ability to log all
 actions done by clients so we can replay the whole game in an effort to make
 desyncs better reproducible. You need to turn this ability on. When turned
@@ -140,8 +141,9 @@
 desync has been fixed; if you, by accident, send us the wrong savegames we
 will not be able to reproduce the desync and thus will be unable to fix it.
 
-3.0) Supported Platforms:
----- --------------------
+
+3.0) Supported platforms
+---- -------------------
 OpenTTD has been ported to several platforms and operating systems. It shouldn't
 be very difficult to port it to a new platform. The currently working platforms
 are:
@@ -157,9 +159,8 @@
   Windows              - Win32 GDI (faster) or SDL or Allegro
 
 
-4.0) Installing and running OpenTTD:
----- -------------------------------
-
+4.0) Installing and running OpenTTD
+---- ------------------------------
 Installing OpenTTD is fairly straightforward. Either you have downloaded an
 archive which you have to extract to a directory where you want OpenTTD to
 be installed, or you have downloaded an installer, which will automatically
@@ -186,9 +187,8 @@
 Online Content". If you do not have an AI but have configured OpenTTD to start
 an AI a message will be shown that the 'dummy' AI has been started.
 
-4.1) (Required) 3rd party files:
----- ---------------------------
-
+4.1) (Required) 3rd party files
+---- --------------------------
 Before you run OpenTTD, you need to put the game's data files into a data/
 directory which can be located in various places addressed in the following
 section.
@@ -248,8 +248,7 @@
 "couldn't find library 'lib-name'". Download that library and try again.
 
 4.2) OpenTTD directories
----- -------------------------------
-
+---- -------------------
 The required 3rd party files listed in the section 4.1 "(Required) 3rd party files"
 as well as other non-compulsory extensions (NewGRFs, AI, heightmaps, scenarios) can be
 placed in a few different locations:
@@ -289,10 +288,8 @@
 have write access on shared directory) and have your openttd.cfg config file in
 personal directory (where the game will then also place savegames and screenshots).
 
-
-4.3) Portable Installations (External Media):
----- ----------------------------------------
-
+4.3) Portable installations (portable media)
+---- ---------------------------------------
 You can install OpenTTD on external media so you can take it with you, i.e.
 using a USB key, or a USB HDD, etc.
 Create a directory where you shall store the game in (i.e. OpenTTD/).
@@ -305,9 +302,8 @@
 again, see section 4.1).
 
 
-5.0) OpenTTD features:
----- -----------------
-
+5.0) OpenTTD features
+---- ----------------
 OpenTTD has a lot of features going beyond the original Transport Tycoon Deluxe
 emulation. Unfortunately, there is currently no comprehensive list of features,
 but there is a basic features list on the web, and some optional features can be
@@ -326,10 +322,8 @@
 * Hovering over a GUI element shows tooltips. This can be changed to right click
   via the advanced settings.
 
-
-5.1) Logging of potentially dangerous actions:
+5.1) Logging of potentially dangerous actions
 ---- ----------------------------------------
-
 OpenTTD is a complex program, and together with NewGRF, it may show a buggy
 behaviour. But not only bugs in code can cause problems. There are several
 ways to affect game state possibly resulting in program crash or multiplayer
@@ -358,8 +352,8 @@
 OpenTTD in debug mode.
 
 
-6.0) Configuration File:
----- -------------------
+6.0) Configuration file
+---- ------------------
 The configuration file for OpenTTD (openttd.cfg) is in a simple Windows-like
 .INI format. It's mostly undocumented. Almost all settings can be changed
 ingame by using the 'Advanced Settings' window.
@@ -368,8 +362,8 @@
 create one after closing.
 
 
-7.0) Compiling:
----- ----------
+7.0) Compiling
+---- ---------
 Windows:
   You need Microsoft Visual Studio .NET. Open the project file
   and it should build automatically. In case you want to build with SDL support
@@ -421,8 +415,8 @@
   will be generated that does not need cwsdpmi.exe by adding the cswdstub.exe
   to the created OpenTTD binary.
 
-7.1) Required/optional libraries:
----- -------------------
+7.1) Required/optional libraries
+---- ---------------------------
 The following libraries are used by OpenTTD for:
   - libSDL/liballegro: hardware access (video, sound, mouse)
   - zlib: (de)compressing of old (0.3.0-1.0.5) savegames, content downloads, heightmaps
@@ -446,7 +440,7 @@
 The compilation of these extra graphics does generally not happen, unless
 you remove the graphics file using "make maintainer-clean".
 
-7.2) Supported compilers:
+7.2) Supported compilers
 ---- -------------------
 The following compilers are known to compile OpenTTD:
   - Microsoft Visual C++ (MSVC) 2005, 2008 and 2010.
@@ -470,8 +464,9 @@
 If any of these compilers can compile OpenTTD again, please let us know.
 Patches to support more compilers are welcome.
 
-8.0) Translating:
----- -------------------
+
+8.0) Translating
+---- -----------
 See http://www.openttd.org/development for up-to-date information.
 
 The use of the online Translator service, located at
@@ -485,8 +480,8 @@
 before beginning the translation process! This avoids double work, as
 someone else may have already started translating to the same language.
 
-8.1) Translation:
----- -------------------
+8.1) Translation
+---- -----------
 So, now that you've notified the development team about your intention to
 translate (You did, right? Of course you did.) you can pick up english.txt
 (found in the SVN repository under /src/lang) and translate.
@@ -503,8 +498,8 @@
     * Lines beginning with ## (such as ##id), other than the first two lines of
       the file
 
-8.2) Previewing:
----- -------------------
+8.2) Previewing
+---- ----------
 In order to view the translation in the game, you need to compile your language
 file with the strgen utility. You can download the precompiled strgen from:
 http://www.openttd.org/download-strgen
@@ -523,9 +518,9 @@
 
 That's all! You should now be able to select the language in the game options.
 
+
 9.0) Troubleshooting
 ---- ---------------
-
 To see all startup options available to you, start OpenTTD with the
 "./openttd -h" option. This might help you tweak some of the settings.
 
@@ -558,8 +553,9 @@
 to see this list. You just have to find the files (http://grfcrawler.tt-forums.net/)
 put them in the data/ folder and you're set to go.
 
-X.X) Credits:
----- --------
+
+X.X) Credits
+---- -------
 The OpenTTD team (in alphabetical order):
   Albert Hofkamp (Alberth)       - GUI expert
   Jean-François Claeys (Belugas) - GUI, newindustries and more