Merge pull request #1 from digitalillusions/fix-doc-language

Language Improvements

Author: losanc

docs/about.md

@@ -1,30 +1,29 @@
 # Description
 
-This is an addon for Blender 3.1+ (might work with 2.8+ but has not been tested) that enables loading of file sequences. The addon comes bundled together with [meshio](https://github.com/nschloe/meshio) which enables the loading of geometric data from a multitude of [file formats](./format.md).
+This is an addon for Blender 3.1+ (it might work with 2.8+ but has not been tested) that enables loading of file sequences. The addon comes bundled together with [meshio](https://github.com/nschloe/meshio) which enables the loading of geometric data from a multitude of [file formats](./format.md).
 
-All data is loaded *just-in-time* when the Blender frame changes, in order to avoid excessive memory consumption. By default, the addon is able to load vertices, lines, triangles and quads. It is also able to automatically extract triangle and quad surface meshes from tetrahedral and hexahedral volume meshes. Scalar and vector attributes on vertices are also imported for visualization purposes. 
+All data is loaded *just-in-time* when the Blender frame changes, in order to avoid excessive memory consumption. By default, the addon is able to load vertices, lines, triangles and quads. It is also able to automatically extract triangle and quad surface meshes from tetrahedral and hexahedral volume meshes. Scalar and vector attributes on vertices are also imported for visualization purposes.
 
 ## Basic usage
 
-Here is a gif to show the basic usage of this addon. In this gif, it shows how to load and render a sequence of particles data
+This video shows the basic usage of this addon, i.e. how to load and render a simple sequence of particle data
 
 ![usage](../images/usage.gif)
 
 ## Affected Blender Settings
 
 This addon will change the value of `Preferences`->`Save & Load` ->`Default To` ->`Relative Paths` to `false`. Default value is `true`. For information can be found [here](https://docs.blender.org/manual/en/latest/editors/preferences/save_load.html#blend-files).
 
-This addon will modify the `sys.path` variable of Blender python environment. It will add the path of this addon into `sys.path`.
-
+This addon will also modify the `sys.path` variable of Blender python environment, by inserting the path of the addon itself. This makes it possible to use the bundled libraries.
 
 ## Dependencies
 
-|name | link | license| description|
-|---|---|---|---|
-|meshio | [link](https://github.com/nschloe/meshio) | MIT| import the mesh|
-|fileseq | [link](https://github.com/justinfx/fileseq) | MIT | detect and load file sequences|
-| rich | [link](https://github.com/Textualize/rich) | MIT| dependency of meshio |
-| python-future | [link](https://github.com/PythonCharmers/python-future) | MIT|  dependency of fileseq|
+| name          | link                                                    | license | description                 |
+| ------------- | ------------------------------------------------------- | ------- | --------------------------- |
+| meshio        | [link](https://github.com/nschloe/meshio)               | MIT     | Loading mesh data           |
+| fileseq       | [link](https://github.com/justinfx/fileseq)             | MIT     | Detection of file sequences |
+| rich          | [link](https://github.com/Textualize/rich)              | MIT     | dependency of meshio        |
+| python-future | [link](https://github.com/PythonCharmers/python-future) | MIT     | dependency of fileseq       |
 
 ## License
 

docs/build.md

@@ -1,9 +1,7 @@
 # Build and install the addon
 
-
 ## Build from source
 
-
 1. Clone the project to download both project and dependencies
 
 ```shell
@@ -19,11 +17,11 @@ python3 build_addon.py
 
 ## Download from release page
 
-Or you can simply download the latest `.zip` file from the [release](https://github.com/InteractiveComputerGraphics/blender-sequence-loader/releases) page
+Or you can simply download the latest `.zip` file from the [releases](https://github.com/InteractiveComputerGraphics/blender-sequence-loader/releases) page.
 
 ## Install the zip file
 
-You can check [here](https://docs.blender.org/manual/en/latest/editors/preferences/addons.html#installing-add-ons) for installing and enabling the addon.
+You can check the official Blender documentation [here](https://docs.blender.org/manual/en/latest/editors/preferences/addons.html#installing-add-ons) for installing and enabling addons.
 
 ## For developers
 
@@ -39,17 +37,16 @@ ln -s extern/fileseq/src/fileseq fileseq
 ln -s extern/python-future/src/future/ future
 ```
 
-Then create a soft link to link from the [blender addon directory](https://docs.blender.org/manual/en/latest/advanced/blender_directory_layout.html)[^1] to the directory where you download and unzip the files. For example,
+Then create a soft link to link from the [blender addon directory](https://docs.blender.org/manual/en/latest/advanced/blender_directory_layout.html)[^1] to the directory where you download and unzip the files. For example this could look like this on MacOS,
+
 ```bash
 ln -s ~/Downloads/blender-sequence-loader ~/Library/Application Support/Blender/3.1/scripts/addons/blender-sequence-loader-dev
 ```
 
-[^1]: By default, `{USER}/scripts/addons`, `{USER}`: Location of configuration files (typically in the user’s home directory). 
-
+[^1]: By default, `{USER}/scripts/addons`, `{USER}`: Location of configuration files (typically in the user’s home directory).
 
 ### Windows Users
 
 You can use [mklink](https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/mklink) to do the same things as *-nix users. [^2]
 
 [^2]: You will need either administrator permission, or [developer mode](https://learn.microsoft.com/en-us/windows/apps/get-started/enable-your-device-for-development).
-

docs/conf.py

@@ -26,6 +26,11 @@
 
 html_theme = "sphinx_rtd_theme"
 html_static_path = ['_static']
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.txt': 'markdown',
+    '.md': 'markdown',
+}
 
 
 myst_heading_anchors = 2

docs/format.md

@@ -43,12 +43,12 @@ The additionally supported file formats are
 
 ## Add support for customized file formats
 
-You can add support for your customized file formats. For example, if you want to support `.example` file formats.
+You can add support for your own customized file formats. For example, if you want to support `.example` file formats.
 
 To do that,
 1. Create a `example.py` file in the folder additional_file_formats
 2. Implement a function `def readexample_to_meshio(filepath):`, which reads the file from `filepath`, then construct a [meshio.Mesh](https://github.com/nschloe/meshio/wiki/meshio-Mesh()-data-structure) object. 
 3. Add `meshio.register_format("example", [".example"], readexample_to_meshio, {".example": None})` in the global space
 4. Add `from . import example` in `additional_file_formats/__init__.py`
 
-You can check [additional_file_formats/bgeo.py](https://github.com/InteractiveComputerGraphics/blender-sequence-loader/blob/main/additional_file_formats/bgeo.py) as an example.
+You can check [additional_file_formats/bgeo.py](https://github.com/InteractiveComputerGraphics/blender-sequence-loader/blob/main/additional_file_formats/bgeo.py) as an example.

docs/frame.md

@@ -0,0 +1,20 @@
+Frame control
+=============
+
+You can use Blenders `driver system <https://docs.blender.org/manual/en/latest/animation/drivers/index.html>`_ to control the frame of the sequence.
+
+Default settings
+*****************
+
+Each sequence has its own property ``Current Frame`` to control its frame. By default, the value equals to the `blender current frame <https://docs.blender.org/manual/en/latest/editors/timeline.html#frame-controls>`_.
+
+.. image:: ../images/current_frame.png
+	:align: center
+
+Change the value
+*****************
+
+Right click on the ``Current Frame`` property, then click ``Edit Driver``. You can check  `here <https://docs.blender.org/manual/en/latest/animation/drivers/drivers_panel.html>`_ for more details about how to edit the driver.
+
+.. image:: ../images/edit_driver.png
+	:align: center

docs/frame.rst

@@ -1,26 +1,26 @@
 # Global Settings
 
 There are two global settings
-1. Print information: default on
-1. Auto Refresh: default off
+
+1. Print information: default `true`
+1. Auto Refresh: default `false`
 
 ## Print information
 
-When this button toggled, it will print information about the sequence imported by this addon, such as name of the object into a file.
+When this button is toggled, it will print information about the sequence imported by this addon, such as name of the object, into a separate file.
 
-The file has the name `bseq_{time}`, `{time}` is the time when rendering starts.
+The file has the naming pattern `bseq_{time}`, where `{time}` is the time when rendering is started.
 
-The file will be in the same direction as [blender render output directory](https://docs.blender.org/manual/en/latest/editors/preferences/file_paths.html#render). [^1]
+The file will be located in the [blender render output directory](https://docs.blender.org/manual/en/latest/editors/preferences/file_paths.html#render). [^1]
 
 ![print](../images/print.png)
 
 [^1]: By default the value is `/tmp`, and this directory does not exit on windows system. So when the directory does not exist, it won't print information into file.
 
-
 ## Auto Refresh
 
-When this button toggled, it will [refresh](./list.md#refresh) **all the sequence whenever frame changes**.
+When this button is toggled, it will [refresh](./list.md#refresh) **all the sequences whenever a frame change occurs**.
 
-This option can be useful when some of the sequences are imported while the data is still being generated and not yet complete. Refreshing all the sequences can detect the frames added after being imported.
+This option can be useful when some of the sequences are imported while the data is still being generated and not yet complete. Refreshing all the sequences can detect the frames that were added after being initially imported.
 
 ![auto refresh](../images/auto_refresh.png)

docs/global.md

@@ -2,35 +2,34 @@
 
 By default, all supported file formats are simply imported as geometry (a collection of vertices, lines, triangles and quads). As such, you should be able to directly play/render the animation if it contains geometry.
 
-Note: When rendering the animation, please turn on the [Lock Interface](https://docs.blender.org/manual/en/latest/interface/window_system/topbar.html?#render-menu)[^1]. This will prevent artifacts from occurring, especially if the user continues to operate the Blender interface during the render process.
+Note: When rendering the animation, please turn on the [Lock Interface](https://docs.blender.org/manual/en/latest/interface/window_system/topbar.html?#render-menu)[^1]. This will prevent artifacts from occurring, especially if the user continues to operate the Blender interface during the render process. This is doubly relevant when using custom normals on meshes, as this might cause Blender to crash instead of just failing to load the correct geometry.
 
 ![lock](../images/lock.png)
 
-[^1]: Or maybe not, I am not 100% percent sure about this.
+[^1]: We have also had users stating that they are able to render perfectly well without enabling this setting, so you might be fine to disable this option if you need to.
 
 ## Imported Sequence
 
-Here you can have an overview of all the sequence imported by this addon. And you can select either one of them, it will change [active object](https://docs.blender.org/manual/en/latest/scene_layout/object/selecting.html#selections-and-the-active-object) to it as well. When [active object](https://docs.blender.org/manual/en/latest/scene_layout/object/selecting.html#selections-and-the-active-object) changes, it will change the selection in this list view as well.
+Here you can have an overview of all the sequences imported by this addon. When selecting a sequence, it will change the selected [active object](https://docs.blender.org/manual/en/latest/scene_layout/object/selecting.html#selections-and-the-active-object) as well. Vice versa, when the [active object](https://docs.blender.org/manual/en/latest/scene_layout/object/selecting.html#selections-and-the-active-object) changes, it will change the selection in this list view as well.
 
 ![list](../images/list.png)
 
 ## Enable & Disable
 
 It is possible to individually enable and disable sequences from updating when the animation frame changes. This is very useful when working with very large files or many sequences as it reduces the computational overhead of loading these sequences. Enabled means, that the sequence will be updated on frame change, and Disabled means that the sequence won't be updated on frame change.
 
-To change individual sequence, you can click on the `ENABLED` or `DISABLED` button in the list view.
+To toggle an individual sequence, you can click on the `ENABLED` or `DISABLED` button in the list view.
 
 ![enable](../images/enable.png)
 
 ### Enable Selected & Disable Selected
 
-When you want to enable or disable multiple sequences. You can [select](https://docs.blender.org/manual/en/latest/scene_layout/object/selecting.html) multiple objects, then click `Enable Selected` or `Disable Selected` to enable/disable all selected objects.
-
+When you want to enable or disable multiple sequences, you can [select](https://docs.blender.org/manual/en/latest/scene_layout/object/selecting.html) multiple objects in the viewport, and then click `Enable Selected` or `Disable Selected` to enable/disable all selected objects.
 
 ## Current Frame
 
-`Current Frame` shows the current frame of sequence being loaded. By default, the value is [blender current frame](https://docs.blender.org/manual/en/latest/editors/timeline.html#frame-controls). For advanced usage, you can find it [here](./frame.md).
+`Current Frame` shows the current frame of sequence being loaded. By default, the value is [blender current frame](https://docs.blender.org/manual/en/latest/editors/timeline.html#frame-controls). For advanced usage, you can refer [here](./frame.md).
 
 ## Refresh
 
-Refresh Sequence can be useful when the sequence is imported while the data is still being generated and not yet complete. Refreshing the sequence can detect the frames added after being imported.
+`Refresh Sequence` can be useful when the sequence is imported while the data is still being generated and not yet complete. Refreshing the sequence can detect the frames added after being imported.