BUILDING.md, CONTRIBUTING.md and INSTALL.md files are added and updated

CCExtractor · Aug 14, 2021 · 37a5542 · 37a5542
1 parent 58f0f10
commit 37a5542
Show file tree

Hide file tree

Showing 3 changed files with 197 additions and 17 deletions.
diff --git a/BUILDING.md b/BUILDING.md
@@ -1,21 +1,19 @@
 # Building FastFingers From Source
 
 FastFingers uses the [CMake](https://cmake.org/) and
-[GNU Make](https://www.gnu.org/software/make/) build tools.
-Along with these tools, some libraries needs to be installed
-to build FastFingers from the source. In the section below
-these dependencies are described.
+[GNU Make](https://www.gnu.org/software/make/) build tools. Along with these tools, some libraries needs to be installed
+to build FastFingers from the source. In the section below these dependencies are described.
 
 ## Table of contents
-- [Building FastFingers From Source](#building-fastfingers-from-source)
-    * [Dependencies](#dependencies)
-        + [Install Dependencies for Ubuntu/Debian](#install-dependencies-for-ubuntu-debian)
-        + [Install Dependencies for Fedora/CentOS](#install-dependencies-for-fedora-centos)
-        + [Install Dependencies for Arch/Manjaro](#install-dependencies-for-arch-manjaro)
-    * [Building and Installing](#building-and-installing)
-        + [Configure the CMake](#configure-the-cmake)
-        + [Compile the source files](#compile-the-source-files)
-        + [Install System-wide](#install-system-wide)
+
+* [Dependencies](#dependencies)
+    + [Install Dependencies for Ubuntu/Debian](#install-dependencies-for-ubuntu-debian)
+    + [Install Dependencies for Fedora/CentOS](#install-dependencies-for-fedora-centos)
+    + [Install Dependencies for Arch/Manjaro](#install-dependencies-for-arch-manjaro)
+* [Building and Installing](#building-and-installing)
+    + [Configure the CMake](#configure-the-cmake)
+    + [Compile the source files](#compile-the-source-files)
+    + [Install System-wide](#install-system-wide)
 
 ## Dependencies
 
@@ -31,7 +29,6 @@ You can install the required libraries and tools from package repositories:
 
 ### Install Dependencies for Ubuntu/Debian
 
-
 ```bash
 sudo apt-get install build-essential cmake libgtk-3-0 libgtk-3-dev
 ```
@@ -42,28 +39,28 @@ sudo apt-get install build-essential cmake libgtk-3-0 libgtk-3-dev
 sudo dnf install make gcc cmake pkg-config gtk3 gtk3-devel
 ```
 
-
 ### Install Dependencies for Arch/Manjaro
 
-
 ```bash
 sudo pacman -S base-devel gtk3 cmake
 ```
 
 ## Building and Installing
 
-
 ### Configure the CMake
+
 ```bash
 cmake -S fastfingers/src -B fastfingers/src/build -DCMAKE_BUILD_TYPE=Release
 ```
 
 ### Compile the source files
+
 ```bash
 cmake --build fastfingers/src/build --config Release
 ```
 
 ### Install System-wide
+
 ```bash
 sudo cmake --build fastfingers/src/build --target install
 ```
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,160 @@
+# Contribute to FastFingers
+
+There are a number of ways you can help improve FastFingers. You can contribute to the project by reporting issues,
+making suggestions and modifying the code.
+
+## Table of contents
+* [Design](#design)
+* [How to add new applications](#how-to-add-new-applications)
+    + [Creating the JSON file](#creating-the-json-file)
+        - [Application object:](#application-object-)
+        - [Shortcut category object:](#shortcut-category-object-)
+        - [Shortcut object:](#shortcut-object-)
+        - [Finalizing](#finalizing)
+    + [Adding the logo](#adding-the-logo)
+    + [Adding the logo to GResource file](#adding-the-logo-to-gresource-file)
+    + [Integrating your work with the project](#integrating-your-work-with-the-project)
+
+## Design
+
+FastFingers is a Linux GUI application. Main libraries and tools used in the project are GTK3, GLib, CMake and cJSON.
+
+The UI designs are stored under "src/ui" in the XML format, which are both human-readable and interpretable by
+GtkBuilder.
+
+FastFingers and Cheatsheet are two different executables. FastFingers starts from main.c and the Cheatsheet app starts
+with cheatsheet.
+
+Pages files are named "(pageName)-page", custom widget files take the widget's name. main.c, fastfingers.c and
+cheatsheet.c files controls the application flow. ff-utils.c file has the utility functions that are used in the
+project.
+
+Keyboard shortcuts are stored in the "data/applications" path. Each application has their owned JSON file with a custom
+format. This format is described in the section below.
+
+## How to add new applications
+
+Application files are stored in the path "data/applications". If you want to add a new application, please read the
+information below to understand the design. If you want to add a new application, you should create a .json file as
+described, add its logo to "src/logo", and add that logo to
+"org.ccextractor.FastFingers.gresource.xml". This progress is explained step by step below.
+
+### Creating the JSON file
+
+Each application has their owned JSON file with a custom format. The name of this json file should only include lower
+case characters and shouldn't contain any whitespace.
+
+#### Application object:
+
+```json
+{
+  "title": "Firefox",
+  "category": "Utility",
+  "recent": [],
+  "group": [
+    ...
+  ]
+}
+```
+
+* title
+    * This key determines the title of the application. This is the name shown in the FastFingers for the application.
+* category
+    * This key determines the category of the application. In the home page, the applications are grouped under the
+      categories, so this information is important for the harmony.
+* recent
+    * This key is used in the application run time. It should be left blank in the source.
+* group
+    * Shortcuts of the applications are stored under the categories, and the group key has an array value that holds
+      those categories.
+
+#### Shortcut category object:
+
+```json
+{
+  "title": "Navigation",
+  "shortcuts": [
+    ...
+  ]
+}
+```
+
+* title
+    * This key determines the title of the shortcut category. This title is shown in the application screen.
+* shortcuts
+    * Shortcuts that belong to this category are stored in this array.
+
+#### Shortcut object:
+
+```json
+  {
+  "title": "Back",
+  "keys": [
+    "Alt",
+    "Left"
+  ],
+  "learned": 0
+}
+```
+
+* title
+    * Title is the both identifier and descriptor of the shortcut. In practice, quiz and quiz result screens, this title
+      is shown. Thi title should be as short as possible.
+* keys
+    * Keys that should be pressed is stored in this array in the same order.
+* learned
+    * Learned key is meaningful for the program and this key should be 0 in the source files.
+
+#### Finalizing
+
+After following the steps above, you should have a JSON structure like this:
+
+```json
+{
+  "title": "Firefox",
+  "category": "Utility",
+  "recent": [],
+  "group": [
+    {
+      "title": "Navigation",
+      "shortcuts": [
+        {
+          "title": "Back",
+          "keys": [
+            "Alt",
+            "Left"
+          ],
+          "learned": 0
+        }
+      ]
+    }
+  ]
+}
+```
+
+To have a greater idea about the JSON files, you can take a look at existing files
+at "[data/applications](https://github.com/CCExtractor/fastfingers/tree/main/data/applications)".
+
+### Adding the logo
+
+You should add the logo of the application to the
+
+path "[src/logo](https://github.com/CCExtractor/fastfingers/tree/main/src/logo)". Name of the file should be in the same
+format with the JSON file, it should consist of lower case characters, and it shouldn't contain whitespace.These logos
+are shown in the home, application, practice and quiz screens. The files scaled automatically in the application, so
+there is no size rule.
+
+### Adding the logo to GResource file
+
+Application holds the logos in its executable. To do this, you should define each logo in the GResource file
+at "[src/org.ccextractor.FastFingers.gresource.xml](https://github.com/CCExtractor/fastfingers/blob/main/src/org.ccextractor.FastFingers.gresource.xml)"
+.
+
+```xml
+    ...
+<file>logo/fileName.png</file>
+```
+
+### Integrating your work with the project
+
+You can send a pull request to integrate all your work with the project.
diff --git a/INSTALL.md b/INSTALL.md
@@ -0,0 +1,23 @@
+# Building FastFingers From Source
+
+FastFingers release Debian, Arch and RPM packages in
+every release. You can download the proper package for
+your Linux system from releases and ## Install them with 
+package managers.
+
+
+## Install the package for Ubuntu/Debian
+
+```bash
+```
+
+## Install the package for Fedora/CentOS
+
+```bash
+```
+
+
+## Install the package for Arch/Manjaro
+
+```bash
+```