Included overview docs

4 files changed, 199 insertions, 0 deletions

diff --git a/docs/documentations/overview_config.d.5 b/docs/documentations/overview_config.d.5
new file mode 100644
index 0000000..a849051
--- /dev/null
+++ b/docs/documentations/overview_config.d.5
@@ -0,0 +1,58 @@
+.TH "GSE CONFIG.D OVERVIEW" "5"
+
+.PP
+The config.d directory hosts all the configuration files that are used to build a system.
+While the building process depends on those files, they are not considered core files (except three), meaning that
+GSE is not requiring those to function. If they miss, GSE will simply skip the part that depends on those.
+.fi
+.PP
+However, while those configuration files are not runtime dependencies for GSE, they are the incarnation
+of GSE, since from those, it provides the means to configure and build the system the way someone wishes and
+control the hosts that run upon that. Therefore, someone can argue, that these files are the most important aspect of
+GSE, since from those, derive all the functions that someone would find interesting and install GSE in the 
+first place.
+.fi
+
+.PP
+.nf
+The config.d directory lies under /usr/lib64/gse and hosts two main sub-directories.
+	I)  System
+	II) Controller
+.fi
+.PP
+The system sub-directory hosts all the configuration files that are used during the system built and configuration.
+Configuration files like hostname, make.conf, portage profile, package.use, system links, fstab entries are common
+files under this sub-directory. 
+
+It was noted above that three files under the config.d directory are considered core files. Those files lie under this
+sub-directory and are:
+.fi
+.PP
+.nf
+	I)   Fstab entries
+	II)  Driver interface
+	III) Catalyst
+.fi
+
+.PP
+The fstab and driver interface files are considered core items, since from those GSE will read what kind of interface 
+it should expect to see or create on the new hosts. For example, boot/system/userdata file system type/size and mount options.
+
+The third and last entry (Catalyst) is important if catalyst is used as the foundation of the new system. The catalyst directory
+hosts the spec files, catalyst.conf and catalystrc files, which will inform catalyst about the built and options it should apply.
+.fi
+
+.PP
+The second main sub-directory is called controller. The controller sub-directory hosts all the configuration files that are used
+from the initramfs functions on the hosts, during the boot-up. Those files are fetched from the hosts on boot-up and are considered
+as a way of server-client communication.
+.fi
+.PP
+Each time a host boots-up, it will search for network connection and if it can establish one, then it will proceed with fetching this
+directory from the server. From those file, the host will be informed about new changes, e.g. fstab changes, hostname changes, server
+IP changes, ssh pub key changes, gpg public key changes,...
+.fi
+.PP
+Since those files provide a way of control from the server to clients, GSE provides an option for masking a specific file or directory.
+A mask informs the controller that no change should happen to that file, whatever the new fetched version instructs.
+.fi
\ No newline at end of file
diff --git a/docs/documentations/overview_controller.5 b/docs/documentations/overview_controller.5
new file mode 100644
index 0000000..f4810c1
--- /dev/null
+++ b/docs/documentations/overview_controller.5
@@ -0,0 +1,51 @@
+.TH "CONTROLLER OVERVIEW" "5"
+
+.PP
+Note: The following entries are part of man 5 gse. For more information about GSE, please refer there.
+.fi
+.SH "CONTROLLER"
+.nf
+\fBThe controller\fR consists from a set of scripts, functions and files that lie inside the initramfs.
+The concept of it, derives from the need to controll and make changes to multiple systems that host the
+images created from the builder. By names definition, the controller is responsible making dicisions
+before the system begins booting, that is, before the initramfs handles the control to the main system.
+
+.TP
+\fBController's functions\fR
+-Fetch configuration data from the server
+-Check local version with the server's version
+-Check the health integrity of SYSFS and BACKUPFS
+-Apply new configuration files to the SYSFS
+-Update runlevels
+-Create new drive interfaces
+-Create filesystems
+-Create and modify LABELS
+-Switch BOOTFS
+-Mount /etc and other directories as tmpfs
+-Decide which partition will be named SYSFS
+-Create,delete and modify subvolumes
+-Even wipe the whole setup and start new
+.fi
+.PP
+.nf
+The above features can be acceced and modifed, while not recommended from the controller modules.
+The modules are located at "$GSE/config.d/controller/modules" and are orginized by categories.
+.fi
+.PP
+.nf
+The controller is built inside the initramfs at the end of the chroot part. While that makes the
+reproduction of the controller a slower process, the reason to include be included at that part,
+is to shield off rebuilding the host's kernel. This feature will be transfered outside the chroot
+phase in the future, making it independent from the rest of the process. Meaning that Part H. and
+Part I. would be moved out of Stage B.
+.fi
+.SH "GSE PROFILE"
+.nf
+The GSE profile, is an experimental profile which aims to enable early functions, features and flags
+for the purpose of assisting computer labs on Research facilities and University labs. 
+The projects idea was born to aid such needs, and the profile is a way reflecting those.
+
+The profile enables global support for programming languages and global support for math functions.
+This profile will be split in other parts in the future, to support embedded systems, by enabling
+fewer flags and emerging as much as possible fewer packages. But for now it is simply tested.
+.fi
\ No newline at end of file
diff --git a/docs/documentations/overview_gse.5 b/docs/documentations/overview_gse.5
new file mode 100644
index 0000000..4abd45b
--- /dev/null
+++ b/docs/documentations/overview_gse.5
@@ -0,0 +1,36 @@
+.TH "GSE OVERVIEW" "5"
+
+.PP
+.nf
+There are 5 important directories regarding GSE.
+.PP
+	I)		The config.d directory under /usr/lib64/gse
+	II)		The scripts directory under /usr/lib64/gse
+	III)	The gse directory under /etc
+	IV)		The dist.d directory, default under /var/tmp/gse
+	V)		The local directory under /var/tmp/gse
+.fi
+
+.PP
+The config.d directory holds all configuration files that describe the items and features to be added or enabled on the system to be built.
+.fi
+.PP
+The scripts directory actually is GSE. This directory holds all the functions that are either initiated directly from /bin/gse or sourced
+during the process. It is not recommended to modify those files, since gse provides many configuration files targeted for the system and additionally
+it provides a custom script mechanism, with which someone could source whatever he wishes, without modifying any core scripts.
+.fi
+.PP
+GSE configuration files. Those files instruct GSE where to look for important items that regard mostly the Part: A Fundamentals, for example: 
+the GSE pub key, stage3 tarball, portage snapshot.
+.fi
+.PP
+The dist.d directory is where GSE will do all the work after the catalyst part, which is a separate process. Under dist.d GSE keeps all the workdirs,
+and Downloaded items (stage3 tarball, portage snapshot, md5sum files,...).
+.fi
+.PP
+The local directory holds all the gse log files, states and extra files important for controlling the building sequence.
+.fi
+.PP
+.nf
+Note: For more technical details of GSE functions and features, please check man 1 gse.
+.fi
\ No newline at end of file
diff --git a/docs/documentations/overview_scripts.5 b/docs/documentations/overview_scripts.5
new file mode 100644
index 0000000..0a65e11
--- /dev/null
+++ b/docs/documentations/overview_scripts.5
@@ -0,0 +1,54 @@
+.TH "GSE CORE SCRIPTS OVERVIEW" "5"
+
+.PP
+.nf
+The core script's that consist GSE are:
+			I)		gse under /bin
+			II)		sinit under /usr/lib64/gse/scripts
+			III)	sinit_functions under /usr/lib64/gse/scripts/functions
+			IV)		catalyst_functions under /usr/lib64/gse/scripts/functions
+			V)		drv_interface under /usr/lib64/gse/scripts/functions
+			VI)		init_stage3_seq under /usr/lib64/gse/scripts/functions
+			VII)	makeconf_ed	under /usr/lib64/gse/scripts/functions
+			VIII)	men_opt under /usr/lib64/gse/scripts/functions
+			IX)		chroot_sinit under /usr/lib64/gse/scripts/chroot_functions
+			X)		cfunctions under /usr/lib64/gse/scripts/chroot_functions
+.fi
+.PP
+The gse script is the first script that runs. From this script the paths, workdirs, configdirs, distdirs are set
+and everything that follows is sourced. The most important thing function that this script provides, is a way to call
+warp function after ensuring that all the above paths and directories have been set and exported. The warp function is
+the main function that initiates the building sequence. It's and autonomous process, meaning that someone could call just
+this function if he had set manually the above directories and paths.
+.fi
+.PP
+The sinit script is the main script that controls Stage: A. For more information about stages and parts, see man 5 gse.
+.fi
+.PP
+The sinit_functions is a file with all the functions that sinit requires to complete the process. Actually this file holds
+almost all functions of Stage: A and it in fact is sourced even before the warp function is called.
+.fi
+.PP
+The catalyst_functions are the set all of functions that are required by the init_stage3_seq scrip.
+.fi
+.PP
+The drv_interfface is a script which generates the driver interface to be created on all host files. From this script, someone
+can set the boot,system,userdata file-systems types and sizes.
+.fi
+.PP
+The init_stage3_seq is a script that is sourced when the catalyst base option is provided. This script will scan for portage snapshot,
+create or download a new one if no local snapshot is found or the one provided fails to satisfy certain conditions. Then, it will initiate
+the building sequence of stage{1,2,3}. For each stage it will automatically read, filter and export the spec files that are provided for the process.
+.fi
+.PP
+Makeconf_ed is a simple script that is either initiated manually from the main menu or automatically by the warp function. This script will use
+a default make.conf files and edit it with MAKEOPTS, EMERGE_DEFAULT_OPTS, SYSTEM ARCH, FEATURES and GENTOO MIRRORS. A completely optional script, that
+wont harm the process if it's missing, however it is recommended to keep it and use it, since it provides a fast way of creating a simple make.conf file, 
+optimized for compilation as described in GCC Optimization wiki page.
+.fi
+.PP
+The chroot_sinit script is the script that controls the Stage: B. This stage actually is a chroot stage, meaning that GSE will chroot to the new
+system, configure it, update it and apply all requested packages, profiles and system links.
+.fi
+.PP The cfunctions is the same as catalyst_functions and sinit_functions. All functions that are required by chroot_sinit lie here.
+.fi
\ No newline at end of file