Documentation grammatical improvements (#1973)

docs/source/building.rst

@@ -26,7 +26,7 @@ On Linux, you will need:
 * qt5-svg
 * pkgconf
 
-On some Linux distributions, all of those packages can be installed with this single command:
+On some Linux distributions, all of these packages can be installed with this single command:
 
 ::
 
@@ -36,14 +36,14 @@ Building steps
 ~~~~~~~~~~~~~~
 
 The official way to build Cutter on Linux is by using CMake.
-First clone the repository with its dependencies:
+First, clone the repository with its dependencies:
 
 .. code-block:: sh
 
    git clone --recurse-submodules https://github.com/radareorg/cutter
 
 
-Then just use CMake to build Cutter and its dependency radare2.
+Then invoke CMake to build Cutter and its dependency radare2.
 
 .. code:: sh
 
@@ -135,7 +135,7 @@ Install Meson:
 
    python -m pip install meson
 
-To compile Cutter run:
+To compile Cutter, run:
 
 .. code:: batch
 
@@ -221,8 +221,8 @@ Or if one wants to explicitely disable an option:
 Compiling Cutter with Breakpad support
 --------------------------------------
 
-If you want to build Cutter with crash handling system, you want prepare Breakpad before.
+If you want to build Cutter with crash handling system, you will want to first prepare Breakpad.
-For this simply run one of the scripts (according to your OS) from root Cutter directory:
+For this, simply run one of the scripts (according to your OS) from root Cutter directory:
     
 .. code:: sh
 
@@ -263,8 +263,8 @@ containing bin/, lib/, include/, etc.) and specify it to CMake using
 
    ./Cutter: error while loading shared libraries: libr_lang.so: cannot open shared object file: No such file or directory
 
-The exact r2 .so file that cannot be found may vary. On some systems linker by default uses RUNPATH instead of RPATH which is incompatible with the way r2 is currently compiled. It results in some of the r2 libraries not being found when running cutter. You can verify if this is the problem by running `ldd ./Cutter`. If all the r2 libraries are missing you have a different problem.
+The exact r2 .so file that cannot be found may vary. On some systems, the linker by default uses RUNPATH instead of RPATH which is incompatible with the way r2 is currently compiled. It results in some of the r2 libraries not being found when running cutter. You can verify if this is the problem by running `ldd ./Cutter`. If all the r2 libraries are missing you have a different problem.
-Workaround is to either add `--disable-new-dtags` linker flag when compiling Cutter or add r2 installation path to LD_LIBRARY_PATH environment variable.
+The workaround is to either add the `--disable-new-dtags` linker flag when compiling Cutter or add the r2 installation path to LD_LIBRARY_PATH environment variable.
 
 ::
 

docs/source/code.rst

@@ -21,7 +21,7 @@ Example:
 Calling a radare2 command
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-There are two ways to do it: 
+There are two ways to call a radare2 command: 
 
 - ``CutterCore::cmd()`` *(Discouraged)* Only use it for commands which yells no output
 - ``CutterCore::cmdj()`` To be used with json commands like ``cmdj("agj")`` or ``cmdj("aflj")``.
@@ -98,10 +98,8 @@ In contrast to the official guidelines of Qt, in Cutter we always use curly brac
 Includes
 ^^^^^^^^
 
-Always try to include only the **needed** definitions inside any header file.
+Strive to include only **required** definitions inside header files.
-The less include in a header file, the better. That is that a header file is
+This will avoid triggering additional unnecessary compilations.
-meant to be included elsewhere, and we want to avoid to trigger every file
-compilation when developping because of a single change in a header file.
 
 If you only need to know that a class exists but don't need the prototype,
 you can declare the class like this:
@@ -120,11 +118,11 @@ And then include the class header inside your .cpp so you can use that class.
 If you need something in the source file (.cpp) that is not a class member,
 then add the include in the source file.
 
-The includes must be ordered from local to global. That is you will first include
+The includes must be ordered from local to global. That is, first include
 any local header file (with doublequotes like `#include "common/Helpers.h"`.
-Then after an empty newline you can include Qt definitions like
+Then, after an empty newline, include Qt definitions like
 `#include <QShortcut>`.
-And then after when needed, include the standard C++ headers you need.
+Finally, include the standard C++ headers you need.
 
 Includes must be sorted by alphabetical order.
 
@@ -144,7 +142,7 @@ function documentation, please use the following format:
 Loops
 ^^^^^
 
-We use C++11 foreach loop style which means any “foreach” loop should
+We use the C++11 foreach loop style, which means any “foreach” loop should
 look like:
 
 .. code:: cpp
@@ -167,7 +165,7 @@ Example:
 Connecting signals
 ^^^^^^^^^^^^^^^^^^
 
-To connect a signal to a slot, this is the preferred way to do it:
+To connect a signal to a slot, this is the preferred syntax:
 
 .. code:: cpp
 

docs/source/common-errors.rst

@@ -1,7 +1,7 @@
 Common errors
 =============
 
-This page lists common issues met by our users.
+This page lists common issues encountered by users.
 
 AppImage crashes
 ----------------
@@ -18,7 +18,7 @@ Compilation error
 r_core development package not found
 ~~~~~~~~~~~~~~~~~~
 
-If you installed radare2 and still encounter this error, could be your
+If you installed radare2 and still encounter this error, it could be that your
 ``PATH`` environment variable is set improperly (doesn’t contain
 ``/usr/local/bin``). That can be, for example, due to ``Qt Creator.app``
 being copied over to ``/Applications``. To fix this, append
@@ -26,7 +26,7 @@ being copied over to ``/Applications``. To fix this, append
 Environment* section in Qt Creator. See the screenshot below should you
 encounter any problems.
 
-On OS X you can also try:
+On macOS, you can also try:
 
 -  ``PKG_CONFIG_PATH=$HOME/bin/prefix/radare2/lib/pkgconfig qmake``
 -  ``PKG_CONFIG_PATH=$HOME/cutter/radare2/pkgcfg qmake`` (for modern
@@ -42,8 +42,8 @@ can add variable ``PKG_CONFIG_PATH`` with value ``/usr/lib/pkgconfig/``
 OS X libjpeg error
 ~~~~~~~~~~~~~~~~~~
 
-On Mac, QT5 apps fail to build on QtCreator if you have the libjpeg lib
+On macOS, QT5 apps fail to build on QtCreator if you have the libjpeg lib
-installed with brew. Run this command to workaround the issue:
+installed with brew. Run this command to work around the issue:
 
 ::
 
@@ -55,4 +55,4 @@ Keyboard layout issue
 Some people report that they have keyboard issues. Usually it is because
 the Xorg layout is wrong. You can check it with: ``setxkbmap -query``
 Most of the time using ``setxkbmap us`` solves the issue, but it might
-not be enough and require some more advanced Xorg configuration.
+not be enough and require a more advanced Xorg configuration.

docs/source/crash-handling-system.rst

@@ -1,11 +1,11 @@
 Crash Handling System
 =====================
 
-Cutter uses `Breakpad <https://github.com/google/breakpad>`__ as backend
+Cutter uses `Breakpad <https://github.com/google/breakpad>`__ as a backend
 for crash handling.
 
-Crash Handling System is disabled by default to do not interfere developers from debugging.
+Crash Handling System is disabled by default to not interfere with developers while debugging.
-To enable this system there is building option ``CUTTER_ENABLE_CRASH_REPORTS``.
+To enable this system, set the ``CUTTER_ENABLE_CRASH_REPORTS`` build option.
 
 Solution description
 --------------------
@@ -15,18 +15,18 @@ There are only 2 source files:
 * ``CrashHandler.h``
 * ``CrashHandler.cpp``
 
-And API is very simple: only one function - ``initCrashHandler()`` that enables Crash Handling System if
+And the API is very simple: One function, ``initCrashHandler()``, enables the Crash Handling System if
-``CUTTER_ENABLE_CRASH_REPORTS`` is true, otherwise does nothing.
+``CUTTER_ENABLE_CRASH_REPORTS`` is true, otherwise it does nothing.
 
-As soon as signal is raised ``crashHandler(int signum)`` is called with signal's code as argument.
+As soon as a signal is raised, ``crashHandler(int signum)`` is called with the signal's code as argument.
-This function first of all writes crash dump to OS's Temp directory to catch core and memory state 
+This function first writes a crash dump to the operating system's temporary directory to catch core and
-as it was at the crash moment.
+memory state as it was at the moment of the crash.
 
-Then crash dialog is shown:
+Then the crash dialog is shown:
 
 .. image :: images/crash-dialog.png
 
-If user chose to create crash dump, prepared dump is moved to directory specified by user.
+If the user chooses to create a crash dump, the prepared dump is moved to the directory specified by user.
-And then success dialog is shown:
+And then the success dialog is shown:
 
 .. image :: images/success-dump-dialog.png

docs/source/index.rst

@@ -1,9 +1,9 @@
 Cutter
 ======
 
-Cutter is a Qt and C++ GUI for radare2. Its goal is making an advanced,
+Cutter is a Qt and C++ GUI for radare2. Its goal is to provide an advanced,
 customizable and FOSS reverse-engineering platform while keeping the
-user experience at mind. Cutter is created by reverse engineers for
+user experience in mind. Cutter was created by reverse engineers for
 reverse engineers.
 
 .. image:: images/screenshot.png
@@ -41,7 +41,7 @@ Want to help the project?
 
 If you want to contribute to Cutter, take a look
 `here <https://github.com/radareorg/cutter/blob/master/CONTRIBUTING.md>`__
-to know what you can do to help the project!
+to learn how you can help improve the project!
 
 .. toctree::
    :maxdepth: 2

docs/source/plugins.rst

@@ -2,8 +2,8 @@ Plugins
 =======
 
 Cutter supports writing plugins in both C++ and Python.
-If you are unsure which one to choose, we strongly suggest starting with Python since
+If you are unsure of which language to choose, starting with Python is strongly suggested as
-it allows for a quicker and easier workflow.
+it provides a faster and simpler workflow.
 
 If you plan to implement support for a new file format or architecture, Cutter plugins are not the correct approach.
 Instead, you will want to implement a radare2 plugin, which is documented `here <https://radare.gitbooks.io/radare2book/plugins/intro.html>`_.