Merge pull request #31 from daafu/patch-4

Update filesystem.rst

tutorials/step_by_step/filesystem.rst

@@ -1,48 +1,38 @@
 .. _doc_filesystem:
 
-Filesystem
+File system
 ==========
 
 Introduction
 ------------
 
-Filesystem usage is yet another hot topic in engine development. This
-means, where are assets stored, how are they accessed, how do multiple
-programmers edit the same repository, etc.
+File systems are yet another hot topic in engine development. The
+file system manages how the assets are stored, and how they are accessed.
+A well designed file system also allows multiple developers to edit the
+same source files and assets while collaborating together.
 
-Initial versions of the engine (and previous iterations before it was
-named Godot) used a database. Assets were stored there and assigned an
-ID. Other approaches were tested, too, with local databases, files with
-metadata, etc. To say truth, and after a long time, simplicity proved to
-be best and Godot stores all assets as files in the flesystem.
+Initial versions of the Godot engine (and previous iterations before it was
+named Godot) used a database. Assets were stored in it and assigned an
+ID. Other approaches were tried as well, such as local databases, files with
+metadata, etc. In the end the simple approach won and now Godot stores
+all assets as files in the file system.
 
 Implementation
 --------------
 
-Godot stores resources to disk. Anything, from a script, to a scene or a
+The file system stores resources on disk. Anything, from a script, to a scene or a
 PNG image is a resource to the engine. If a resource contains properties
-that reference other resources on disk, the path to that resource is
-included. If it has sub-resources that are built-in, the resource is
+that reference other resources on disk, the paths to those resources are also
+included. If a resource has sub-resources that are built-in, the resource is
 saved in a single file together with all the bundled sub-resources. For
-example, a font resource is often saved with the character textures
-bundled inside.
+example, a font resource is often bundled together with the font textures.
 
-Metadata files were also dropped and the whole engine design tries to
-avoid them. The reason for this is simple, existing asset managers and
-VCSs are just much better than anything we can implement, so Godot tries
-the best to play along with SVN, Git, Mercurial, Perforce, etc.
+In general the the Godot file system avoids using metadata files. The reason for
+this is simple, existing asset managers and VCSs are just much better than
+anything we can implement, so Godot tries the best to play along with SVN,
+Git, Mercurial, Perforce, etc.
 
-engine.cfg
-----------
-
-The mere existence of this file marks that there is a Godot project in
-that directory and all sub-directories.
-
-This file contains the project configuration in plain text, win.ini
-style, though it will work to mark the existence of a project even if
-the file is empty.
-
-Example of a filesystem:
+Example of a file system contents:
 
 ::
 
@@ -51,11 +41,22 @@ Example of a filesystem:
     /enemy/enemy.gd
     /enemy/enemysprite.png
     /player/player.gd
+    
+engine.cfg
+----------
+
+The engine.cfg file is the project description file, and it is always found at
+the root of the project, in fact it's location defines where the root is. This
+is the first file that Godot looks for when opening a project.
+
+This file contains the project configuration in plain text, using the win.ini
+format. Even an empty engine.cfg can function as a basic definition of a blank
+project.
 
-Directory delimiter
+Path delimiter
 -------------------
 
-Godot only supports ``/`` as a directory delimiter. This is done for
+Godot only supports ``/`` as a path delimiter. This is done for
 portability reasons. All operating systems support this, even Windows,
 so a path such as ``c:\project\engine.cfg`` needs to be typed as
 ``c:/project/engine.cfg``.
@@ -63,48 +64,48 @@ so a path such as ``c:\project\engine.cfg`` needs to be typed as
 Resource path
 -------------
 
-For accessing resources, using the host OS filesystem layout can be
-cumbersome and non portable. To solve this problem, the specal path
+When accessing resources, using the host OS file system layout can be
+cumbersome and non-portable. To solve this problem, the special path
 ``res://`` was created.
 
 The path ``res://`` will always point at the project root (where
 engine.cfg is located, so in fact ``res://engine.cfg`` is always
 valid).
 
-This filesystem is read-write only when running the project locally from
+This file system is read-write only when running the project locally from
 the editor. When exported or when running on different devices (such as
-phones or consoles, or running from DVD), the filesystem will become
+phones or consoles, or running from DVD), the file system will become
 read-only and writing will no longer be permitted.
 
 User path
 ---------
 
-Writing to disk is still needed often, from doing a savegame to
-downloading content packs. For this, the engine ensures that there is a
+Writing to disk is still often needed for various tasks such as saving game
+state or downloading content packs. To this end, the engine ensures that there is a
 special path ``user://`` that is always writable.
 
-Host filesystem
+Host file system
 ---------------
 
-Of course, opening the host filesystem always works, as this is always
-useful when Godot is used to write tools, but for shipped projects this
-is discouraged and may not even be supported in some platforms.
+Alternatively host file system paths can also be used, but this is not recommended
+for a released product as these paths are not guaranteed to work on all platforms.
+However, using host file system paths can be very useful when writing development
+tools in Godot!
 
 Drawbacks
 ---------
 
-Not everything is rosy. Using resources and files and the plain
-filesystem has two main drawbacks. The first is that moving assets
-around (renaming them or moving them from a directory to another inside
-the project) once they are referenced is not that easy. If this is done,
-then dependencies will need to be re-satisfied upon load.
-
-The second is that under Windows or OSX, file access is case
-insensitive. If a developer works in this operating system and saves a
-file like "myfile.PNG", then references it as "myfile.png", it will work
-there, but not on any other platform, such as Linux, Android, etc. It
-may also not work on exported binaries, which use a compressed package
-for files.
-
-Because of this, please instruct your team to use a specific naming
-convention for files when working with Godot!
+There are some drawbacks to this simple file system design. The first issue is that
+moving assets around (renaming them or moving them from one path to another inside
+the project) will break existing references to these assets. These references will
+have to be re-defined to point at the new asset location.
+
+The second is that under Windows and OSX file and path names are case insensitive.
+If a developer working in a case insensitive host file system saves an asset as "myfile.PNG",
+but then references it as "myfile.png", it will work just fine on their platorm, but not
+on other platforms, such as Linux, Android, etc. This may also apply to exported binaries,
+which use a compressed package to store all files.
+
+It is recommend that your team clearly defines a naming convention for files when
+working with Godot! One simple full-proof convention is to only allow lowercase
+file and path names.