diff --git a/Identity/Manual/Directories/chapter-menu.texi b/Identity/Manual/Directories/chapter-menu.texi index d4f295e..f3cdc82 100644 --- a/Identity/Manual/Directories/chapter-menu.texi +++ b/Identity/Manual/Directories/chapter-menu.texi @@ -36,9 +36,9 @@ * Directories trunk Scripts Functions Locale:: * Directories trunk Scripts Functions Manual:: * Directories trunk Scripts Functions Path:: +* Directories trunk Scripts Functions Prepare:: * Directories trunk Scripts Functions Render:: * Directories trunk Scripts Functions Render Config:: * Directories trunk Scripts Functions Shell:: * Directories trunk Scripts Functions Svg:: -* Directories trunk Scripts Functions Verify:: @end menu diff --git a/Identity/Manual/Directories/chapter-nodes.texi b/Identity/Manual/Directories/chapter-nodes.texi index 28ae355..f6ce972 100644 --- a/Identity/Manual/Directories/chapter-nodes.texi +++ b/Identity/Manual/Directories/chapter-nodes.texi @@ -183,6 +183,11 @@ @cindex Directories trunk Scripts Functions Path @include Directories/trunk/Scripts/Functions/Path.texi +@node Directories trunk Scripts Functions Prepare +@section The @file{trunk/Scripts/Functions/Prepare} Directory +@cindex Directories trunk Scripts Functions Prepare +@include Directories/trunk/Scripts/Functions/Prepare.texi + @node Directories trunk Scripts Functions Render @section The @file{trunk/Scripts/Functions/Render} Directory @cindex Directories trunk Scripts Functions Render @@ -203,8 +208,3 @@ @cindex Directories trunk Scripts Functions Svg @include Directories/trunk/Scripts/Functions/Svg.texi -@node Directories trunk Scripts Functions Verify -@section The @file{trunk/Scripts/Functions/Verify} Directory -@cindex Directories trunk Scripts Functions Verify -@include Directories/trunk/Scripts/Functions/Verify.texi - diff --git a/Identity/Manual/Directories/trunk/Identity.texi b/Identity/Manual/Directories/trunk/Identity.texi index 2c4b7e7..19e8006 100644 --- a/Identity/Manual/Directories/trunk/Identity.texi +++ b/Identity/Manual/Directories/trunk/Identity.texi @@ -195,7 +195,7 @@ centos-art render trunk/Identity/Path/To/Dir @strong{Warning} If the @command{centos-art} command-line is not found in your workstation, it is probably because you haven't prepared your workstation for using The CentOS Artwork Repository yet. -@xref{Directories trunk Scripts Functions Verify}, for more +@xref{Directories trunk Scripts Functions Prepare}, for more information. @end quotation diff --git a/Identity/Manual/Directories/trunk/Scripts/Functions.texi b/Identity/Manual/Directories/trunk/Scripts/Functions.texi index 17fa889..82b5ea2 100755 --- a/Identity/Manual/Directories/trunk/Scripts/Functions.texi +++ b/Identity/Manual/Directories/trunk/Scripts/Functions.texi @@ -1211,7 +1211,7 @@ available for you to use: @comment --- Removed(* Directories trunk Scripts Functions Render Config::) --- @comment --- Removed(* Directories trunk Scripts Functions Shell::) --- @comment --- Removed(* Directories trunk Scripts Functions Svg::) --- -@comment --- Removed(* Directories trunk Scripts Functions Verify::) --- +* Directories trunk Scripts Functions Prepare:: @end menu @subsection See also diff --git a/Identity/Manual/Directories/trunk/Scripts/Functions/Prepare.texi b/Identity/Manual/Directories/trunk/Scripts/Functions/Prepare.texi new file mode 100644 index 0000000..ca4d1c5 --- /dev/null +++ b/Identity/Manual/Directories/trunk/Scripts/Functions/Prepare.texi @@ -0,0 +1,245 @@ +@subsection Goals + +This section exists to organize files related to @file{centos-art.sh} +script @samp{verify} functionality. The @samp{verify} +functionality of @file{centos-art.sh} script helps you to verify the +workstation configuration you are planning to use as host for your +working copy of CentOS Artwork Repository. + +@subsection Description + +The first time you download CentOS Artwork Repository you need to +configure your workstation in order to use @file{centos-art.sh} +script. These preliminar configurations are based mainly on auxiliar +RPM packages installation, symbolic links creations, and environment +variables definitions. The @samp{verify} functionality of +@file{centos-art.sh} script guides you through this preliminar +configuration process. + +If this is the first time you run @file{centos-art.sh} script, the +appropriate way to use its @samp{verify} functionality is not using +the @file{centos-art.sh} script directly, but the absolute path to +@command{centos-art.sh} script instead (i.e., +@file{~/artwork/trunk/Scripts/Bash/centos-art.sh}). This is necessary +because @file{centos-art} symbolic link, under @file{~/bin/} +directory, has not been created yet. + +@subsubsection Packages + +Installation of auxiliar RPM packages provides the software required +to manipulate files inside the repository (e.g., image files, +documentation files, translation files, script files, etc.). Most of +RPM packages @command{centos-art.sh} script uses are shipped with +CentOS distribution, and can be installed from CentOS base repository. +The only exception is @samp{inkscape}, the package we use to +manipulate SVG files. The @samp{inkscape} package is not inside +CentOS distribution so it needs to be installed from third party +repositories. + +@quotation +@strong{Note} Configuration of third party repositories inside CentOS +distribution is described in CentOS wiki, specifically in the +following URL: +@url{http://wiki.centos.org/AdditionalResources/Repositories} +@end quotation + +Before installing packages, the @file{centos-art.sh} script uses +@command{sudo} to request root privileges to execute @command{yum} +installation functionality. If your user isn't defined as a +privileged user---at least to run @command{yum} commands--- inside +@file{/etc/sudoers} configuration file, you will not be able to +perform package installation tasks as set in @file{centos-art.sh} +script @samp{verify} functionality. + +Setting sudo privileges to users is an administrative task you have to +do by yourself. If you don't have experience with @command{sudo} +command, please read its man page running the command: @command{man +sudo}. This reading will be very useful, and with some practice, you +will be able to configure your users to have @command{sudo} +privileges. + +@subsubsection Links + +Creation of symbolic links helps us to alternate between different +implementations of @file{centos-art.sh} script-line (e.g., +@file{centos-art.sh}, for Bash implementation; @file{centos-art.py}, +for Python implementation; @file{centos-art.pl}, for Perl +implementation; and so on for other implementations). The +@file{centos-art.sh} script-line definition takes place inside your +personal binary (@file{~/bin/}) directory in order to make the script +implementation ---the one that @file{centos-art} links to--- available +to @var{PATH} environment variable. + +Creation of symbolic links helps us to reuse components from repository +working copy. For example, color information files maintained inside +your working copy must never be duplicated inside program-specific +configuration directories that uses them in your workstation (e.g., +Gimp, Inkscape, etc.). Instead, a symbolic link must be created for +each one of them, from program-specific configuration directories to +files in the working copy. In this configuration, when someone +commits changes to color information files up to central repository, +they---the changes committed--- will be immediatly available to your +programs the next time you update your working copy ---the place +inside your workstation those color information files are stored---. + +Creation of symbolic links helps us to make @file{centos-art.sh} +script functionalities available outside @file{trunk/} repository +directory structure, but at its same level in repository tree. This is +useful if you need to use the ``render'' functionality of +@command{centos-art.sh} under @file{branches/} repository directory +structure as you usually do inside @file{trunk/} repository directory +structure. As consequence of this configuration, automation scripts +cannot be branched under @file{branches/Scripts} directory structure. + +@subsubsection Environment variables + +Definition of environemnt variables helps us to set default values to +our user session life. The user session environment variable defintion +takes place in the user's @file{~/.bash_profile} file. The +@samp{verify} functionality of @file{centos-art.sh} script doesn't +modify your @file{~/.bash_profile} file. + +The @samp{verify} functionality of @file{centos-art.sh} script +evaluates the following environment variables: + +@table @env +@item EDITOR +Default text editor. + +The @file{centos-art.sh} script uses default text @env{EDITOR} to edit +pre-commit subversion messages, translation files, configuration +files, script files, and similar text-based files. + +If @env{EDITOR} environment variable is not set, @file{centos-art.sh} +script uses @file{/usr/bin/vim} as default text editor. Otherwise, the +following values are recognized by @file{centos-art.sh} script: + +@itemize +@item @file{/usr/bin/vim} +@item @file{/usr/bin/emacs} +@item @file{/usr/bin/nano} +@end itemize + +If no one of these values is set in @env{EDITOR} environment variable, +@file{centos-art.sh} uses @file{/usr/bin/vim} text editor by default. + +@item TEXTDOMAIN + +Default domain used to retrieve translated messages. This variable is +set in @file{initFunctions.sh} and shouldn't be changed. + +@item TEXTDOMAINDIR + +Default directory used to retrieve translated messages. This variable +is set in @file{initFunctions.sh} and shouldn't be changed. + +@item LANG + +Default locale information. + +This variable is initially set in the configuration process of CentOS +distribution installer (i.e., Anaconda), specifically in the +@samp{Language} step; or once installed using the +@command{system-config-language} tool. + +The @file{centos-art.sh} script uses the @var{LANG} environment +variable to know in which language the script messages are printed +out. + +@item TZ + +Default time zone representation. + +This variable is initially set in the configuration process of CentOS +distribution installer (i.e., Anaconda), specifically in the +@samp{Date and time} step; or once installed using the +@command{system-config-date} tool. + +The @file{centos-art.sh} script doesn't use the @var{TZ} environment +variable information at all. Instead, this variable is used by the +system shell to show the time information according to your phisical +location on planet Earth. + +Inside your computer, the time information is firstly set in the BIOS +clock (which may need correction), and later in the configuration +process of CentOS distribution installer (or later, by any of the +related configuration tools inside CentOS distribution). Generally, +setting time information is a straight-forward task and configuration +tools available do cover most relevant location. However, if you need +a time precision not provided by the configuration tools available +inside CentOS distribution then, using @var{TZ} variable may be +necessary. + +@quotation +@strong{Convenction} In order to keep changes syncronized between +central repository and its working copies: configure both repository +server and workstations (i.e., the place where each working copy is +set on) to use Coordinated Universal Time (UTC) as base time +representation. Later, correct the time information for your specific +location using time zone correction. +@end quotation + +The format of @var{TZ} environment variable is described in +@file{tzset(3)} manual page. + +@end table + +@subsection Usage + +@table @command + +@item centos-art verify --packages + +Verify required packages your workstation needs in order to run the +@file{centos-art.sh} script correctly. If there are missing packages, +the @file{centos-art.sh} script asks you to confirm their +installation. When installing packages, the @file{centos-art.sh} +script uses the @command{yum} application in order to achieve the +task. + +In case all packages required by @file{centos-art.sh} script are +already installed in your workstation, the message @samp{The required +packages are already installed.} is output for you to know. + +@item centos-art verify --links + +Verify required links your workstation needs in order to run the +centos-art command correctly. If any required link is missing, the +@command{centos-art.sh} script asks you to confirm their installation. +To install required links, the @command{centos-art.sh} script uses the +@command{ln} command. + +In case all links required by @file{centos-art.sh} script are already +created in your workstation, the message @samp{The required links are +already installed.} is output for you to know. + +In case a regular file exists with the same name of a required link, +the @file{centos-art.sh} script outputs the @samp{Already exists as +regular file.} message when listing required links that will be +installed. Of course, as there is already a regular file where must be +a link, no link is created. In such cases the @file{centos-art.sh} +script will fall into a continue installation request for that missing +link. To end this continue request you can answer @samp{No}, or +remove the existent regular file to let @file{centos-art.sh} script +install the link on its place. + +@item centos-art verify --environment +@itemx centos-art verify --environment --filter='regex' + +Output a brief description of environment variables used by +@file{centos-art.sh} script. + +If @samp{--filter} option is provided, output is reduced as defined in +the @samp{regex} regular expression value. If @samp{--filter} option +is specified but @samp{regex} value is not, the @file{centos-art.sh} +script outputs information as if @samp{--filter} option had not been +provided at all. + +@end table + +@subsection See also + +@menu +* Directories trunk Scripts:: +@comment --- Removed(* Directories trunk Scripts Functions::) --- +@end menu diff --git a/Identity/Manual/Directories/trunk/Scripts/Functions/Verify.texi b/Identity/Manual/Directories/trunk/Scripts/Functions/Verify.texi deleted file mode 100644 index ca4d1c5..0000000 --- a/Identity/Manual/Directories/trunk/Scripts/Functions/Verify.texi +++ /dev/null @@ -1,245 +0,0 @@ -@subsection Goals - -This section exists to organize files related to @file{centos-art.sh} -script @samp{verify} functionality. The @samp{verify} -functionality of @file{centos-art.sh} script helps you to verify the -workstation configuration you are planning to use as host for your -working copy of CentOS Artwork Repository. - -@subsection Description - -The first time you download CentOS Artwork Repository you need to -configure your workstation in order to use @file{centos-art.sh} -script. These preliminar configurations are based mainly on auxiliar -RPM packages installation, symbolic links creations, and environment -variables definitions. The @samp{verify} functionality of -@file{centos-art.sh} script guides you through this preliminar -configuration process. - -If this is the first time you run @file{centos-art.sh} script, the -appropriate way to use its @samp{verify} functionality is not using -the @file{centos-art.sh} script directly, but the absolute path to -@command{centos-art.sh} script instead (i.e., -@file{~/artwork/trunk/Scripts/Bash/centos-art.sh}). This is necessary -because @file{centos-art} symbolic link, under @file{~/bin/} -directory, has not been created yet. - -@subsubsection Packages - -Installation of auxiliar RPM packages provides the software required -to manipulate files inside the repository (e.g., image files, -documentation files, translation files, script files, etc.). Most of -RPM packages @command{centos-art.sh} script uses are shipped with -CentOS distribution, and can be installed from CentOS base repository. -The only exception is @samp{inkscape}, the package we use to -manipulate SVG files. The @samp{inkscape} package is not inside -CentOS distribution so it needs to be installed from third party -repositories. - -@quotation -@strong{Note} Configuration of third party repositories inside CentOS -distribution is described in CentOS wiki, specifically in the -following URL: -@url{http://wiki.centos.org/AdditionalResources/Repositories} -@end quotation - -Before installing packages, the @file{centos-art.sh} script uses -@command{sudo} to request root privileges to execute @command{yum} -installation functionality. If your user isn't defined as a -privileged user---at least to run @command{yum} commands--- inside -@file{/etc/sudoers} configuration file, you will not be able to -perform package installation tasks as set in @file{centos-art.sh} -script @samp{verify} functionality. - -Setting sudo privileges to users is an administrative task you have to -do by yourself. If you don't have experience with @command{sudo} -command, please read its man page running the command: @command{man -sudo}. This reading will be very useful, and with some practice, you -will be able to configure your users to have @command{sudo} -privileges. - -@subsubsection Links - -Creation of symbolic links helps us to alternate between different -implementations of @file{centos-art.sh} script-line (e.g., -@file{centos-art.sh}, for Bash implementation; @file{centos-art.py}, -for Python implementation; @file{centos-art.pl}, for Perl -implementation; and so on for other implementations). The -@file{centos-art.sh} script-line definition takes place inside your -personal binary (@file{~/bin/}) directory in order to make the script -implementation ---the one that @file{centos-art} links to--- available -to @var{PATH} environment variable. - -Creation of symbolic links helps us to reuse components from repository -working copy. For example, color information files maintained inside -your working copy must never be duplicated inside program-specific -configuration directories that uses them in your workstation (e.g., -Gimp, Inkscape, etc.). Instead, a symbolic link must be created for -each one of them, from program-specific configuration directories to -files in the working copy. In this configuration, when someone -commits changes to color information files up to central repository, -they---the changes committed--- will be immediatly available to your -programs the next time you update your working copy ---the place -inside your workstation those color information files are stored---. - -Creation of symbolic links helps us to make @file{centos-art.sh} -script functionalities available outside @file{trunk/} repository -directory structure, but at its same level in repository tree. This is -useful if you need to use the ``render'' functionality of -@command{centos-art.sh} under @file{branches/} repository directory -structure as you usually do inside @file{trunk/} repository directory -structure. As consequence of this configuration, automation scripts -cannot be branched under @file{branches/Scripts} directory structure. - -@subsubsection Environment variables - -Definition of environemnt variables helps us to set default values to -our user session life. The user session environment variable defintion -takes place in the user's @file{~/.bash_profile} file. The -@samp{verify} functionality of @file{centos-art.sh} script doesn't -modify your @file{~/.bash_profile} file. - -The @samp{verify} functionality of @file{centos-art.sh} script -evaluates the following environment variables: - -@table @env -@item EDITOR -Default text editor. - -The @file{centos-art.sh} script uses default text @env{EDITOR} to edit -pre-commit subversion messages, translation files, configuration -files, script files, and similar text-based files. - -If @env{EDITOR} environment variable is not set, @file{centos-art.sh} -script uses @file{/usr/bin/vim} as default text editor. Otherwise, the -following values are recognized by @file{centos-art.sh} script: - -@itemize -@item @file{/usr/bin/vim} -@item @file{/usr/bin/emacs} -@item @file{/usr/bin/nano} -@end itemize - -If no one of these values is set in @env{EDITOR} environment variable, -@file{centos-art.sh} uses @file{/usr/bin/vim} text editor by default. - -@item TEXTDOMAIN - -Default domain used to retrieve translated messages. This variable is -set in @file{initFunctions.sh} and shouldn't be changed. - -@item TEXTDOMAINDIR - -Default directory used to retrieve translated messages. This variable -is set in @file{initFunctions.sh} and shouldn't be changed. - -@item LANG - -Default locale information. - -This variable is initially set in the configuration process of CentOS -distribution installer (i.e., Anaconda), specifically in the -@samp{Language} step; or once installed using the -@command{system-config-language} tool. - -The @file{centos-art.sh} script uses the @var{LANG} environment -variable to know in which language the script messages are printed -out. - -@item TZ - -Default time zone representation. - -This variable is initially set in the configuration process of CentOS -distribution installer (i.e., Anaconda), specifically in the -@samp{Date and time} step; or once installed using the -@command{system-config-date} tool. - -The @file{centos-art.sh} script doesn't use the @var{TZ} environment -variable information at all. Instead, this variable is used by the -system shell to show the time information according to your phisical -location on planet Earth. - -Inside your computer, the time information is firstly set in the BIOS -clock (which may need correction), and later in the configuration -process of CentOS distribution installer (or later, by any of the -related configuration tools inside CentOS distribution). Generally, -setting time information is a straight-forward task and configuration -tools available do cover most relevant location. However, if you need -a time precision not provided by the configuration tools available -inside CentOS distribution then, using @var{TZ} variable may be -necessary. - -@quotation -@strong{Convenction} In order to keep changes syncronized between -central repository and its working copies: configure both repository -server and workstations (i.e., the place where each working copy is -set on) to use Coordinated Universal Time (UTC) as base time -representation. Later, correct the time information for your specific -location using time zone correction. -@end quotation - -The format of @var{TZ} environment variable is described in -@file{tzset(3)} manual page. - -@end table - -@subsection Usage - -@table @command - -@item centos-art verify --packages - -Verify required packages your workstation needs in order to run the -@file{centos-art.sh} script correctly. If there are missing packages, -the @file{centos-art.sh} script asks you to confirm their -installation. When installing packages, the @file{centos-art.sh} -script uses the @command{yum} application in order to achieve the -task. - -In case all packages required by @file{centos-art.sh} script are -already installed in your workstation, the message @samp{The required -packages are already installed.} is output for you to know. - -@item centos-art verify --links - -Verify required links your workstation needs in order to run the -centos-art command correctly. If any required link is missing, the -@command{centos-art.sh} script asks you to confirm their installation. -To install required links, the @command{centos-art.sh} script uses the -@command{ln} command. - -In case all links required by @file{centos-art.sh} script are already -created in your workstation, the message @samp{The required links are -already installed.} is output for you to know. - -In case a regular file exists with the same name of a required link, -the @file{centos-art.sh} script outputs the @samp{Already exists as -regular file.} message when listing required links that will be -installed. Of course, as there is already a regular file where must be -a link, no link is created. In such cases the @file{centos-art.sh} -script will fall into a continue installation request for that missing -link. To end this continue request you can answer @samp{No}, or -remove the existent regular file to let @file{centos-art.sh} script -install the link on its place. - -@item centos-art verify --environment -@itemx centos-art verify --environment --filter='regex' - -Output a brief description of environment variables used by -@file{centos-art.sh} script. - -If @samp{--filter} option is provided, output is reduced as defined in -the @samp{regex} regular expression value. If @samp{--filter} option -is specified but @samp{regex} value is not, the @file{centos-art.sh} -script outputs information as if @samp{--filter} option had not been -provided at all. - -@end table - -@subsection See also - -@menu -* Directories trunk Scripts:: -@comment --- Removed(* Directories trunk Scripts Functions::) --- -@end menu