diff --git a/Manuals/Filesystem/trunk/Locales.texi b/Manuals/Filesystem/trunk/Locales.texi index 8ea4ddd..4de4d93 100644 --- a/Manuals/Filesystem/trunk/Locales.texi +++ b/Manuals/Filesystem/trunk/Locales.texi @@ -51,6 +51,6 @@ Automation of localization tasks is achived through the @code{locale} functionality of command-line interface. @menu -* trunk Scripts Bash centos-art Functions Locale:: +* trunk Scripts Bash cli Functions Locale:: @end menu diff --git a/Manuals/Filesystem/trunk/Scripts/Bash/centos-art.texi b/Manuals/Filesystem/trunk/Scripts/Bash/centos-art.texi deleted file mode 100755 index e69de29..0000000 --- a/Manuals/Filesystem/trunk/Scripts/Bash/centos-art.texi +++ /dev/null diff --git a/Manuals/Filesystem/trunk/Scripts/Bash/centos-art/Functions.texi b/Manuals/Filesystem/trunk/Scripts/Bash/centos-art/Functions.texi deleted file mode 100755 index 2a421ab..0000000 --- a/Manuals/Filesystem/trunk/Scripts/Bash/centos-art/Functions.texi +++ /dev/null @@ -1,1222 +0,0 @@ -@subsection Goals - -The @file{trunk/Scripts/Bash/Functions} directory exists to organize -@file{centos-art.sh} specific functionalities. - -@subsection Description - -The specific functions of @file{centos-art.sh} script are designed -with ``Software Toolbox'' philosophy (@pxref{Toolbox -introduction,,,coreutils.info}) in mind: each program ``should do one -thing well''. Inside @file{centos-art.sh} script, each specific -functionality is considered a program that should do one thing well. -Of course, if you find that they still don't do it, feel free to -improve them in order for them to do so. - -The specific functions of @file{centos-art.sh} script are organized -inside specific directories under @file{trunk/Scripts/Bash/Functions} -location. Each specific function directory should be named as the -function it represents, with the first letter in uppercase. For -example, if the function name is @code{render}, the specific function -directory for it would be @samp{trunk/Scripts/Bash/Functions/Render}. - -To better understand how specific functions of @file{centos-art.sh} -script are designed, lets create one function which only goal is to -output different kind of greetings to your screen. - -When we create specific functions for @file{centos-art.sh} script it -is crucial to know what these functions will do exactly and if there -is any function that already does what we intend to do. If there is no -one, it is good time to create them then. Otherwise, if -functionalities already available don't do what you exactly expect, -contact their authors and work together to improve them. - -@quotation -@strong{Tip} Join CentOS developers mailing list -@email{centos-art@@centos.org} to share your ideas. -@end quotation - -It is also worth to know what global functions and variables do we -have available inside @file{centos-art.sh} script, so advantage can be -taken from them. Global variables are defined inside global function -scripts. Global functions scripts are stored immediatly under -@file{trunk/Scripts/Bash/Functions} directory, in files begining with -@samp{cli} prefix. - -OK, let's begin with our functionality example. - -What function name do we use? Well, lets use @code{greet}. Note that -@samp{hello} word is not a verb; but an expression, a kind of -greeting, an interjection specifically. In contrast, @samp{greet} is a -verb and describes what we do when we say @samp{Hello!}, @samp{Hi!}, -and similar expressions. - -So far, we've gathered the following function information: - -@verbatim -Name: greet -Path: trunk/Scripts/Bash/Functions/Greet -File: trunk/Scripts/Bash/Functions/Greet/greet.sh -@end verbatim - -The @file{greet.sh} function script is the first file -@file{centos-art.sh} script loads when the @samp{greet} functionality -is called using commands like @samp{centos-art greet --hello='World'}. -The @file{greet.sh} function script contains the @code{greet} function -definition. - -Inside @file{centos-art.sh} script, as convenction, each function -script has one top commentary, followed by one blank line, and then -one function defintion below it only. - -Inside @file{centos-art.sh} script functions, top commentaries have -the following components: the functionality description, one-line for -copyright note with your personal information, the license under -which the function source code is released ---the @file{centos-art.sh} -script is released as GPL, so do all its functions---, the @code{$Id$} -keyword of Subversion is later expanded by @command{svn propset} -command. - -In our @code{greet} function example, top commentary for -@file{greet.sh} function script would look like the following: - -@verbatim -#!/bin/bash -# -# greet.sh -- This function outputs different kind of greetings to -# your screen. Use this function to understand how centos-art.sh -# script specific functionalities work. -# -# Copyright (C) YEAR YOURFULLNAME -# -# This program is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 2 of the License, or -# (at your option) any later version. -# -# This program is distributed in the hope that it will be useful, but -# WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -# General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with this program; if not, write to the Free Software -# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 -# USA. -# -# ---------------------------------------------------------------------- -# $Id$ -# ---------------------------------------------------------------------- -@end verbatim - -After top commentary, separated by one blank line, the @code{greet} -function definition would look like the following: - -@verbatim -function greet { - - # Define global variables. - - # Define command-line interface. - greet_getActions - -} -@end verbatim - -The first definition inside @code{greet} function, are global -variables that will be available along @code{greet} function execution -environment. This time we didn't use global variable definitions for -@code{greet} function execution environment, so we left that section -empty. - -Later, we call @code{greet_getActions} function to define the -command-line interface of @code{greet} functionality. The command-line -interface of @code{greet} functionality defines what and how actions -are performed, based on arguments combination passed to -@file{centos-art.sh} script. - -@verbatim -function greet_getActions { - - case "$ACTIONNAM" in - - --hello ) - greet_doHello - ;; - - --bye ) - greet_doBye - ;; - - * ) - cli_printMessage "`gettext "The option provided is not valid."`" - cli_printMessage "$(caller)" 'AsToKnowMoreLine' - - esac - -} -@end verbatim - -The @var{ACTIONNAM} global variable is defined in @file{cli.sh} -function script and contains the value passed before the equal sign -(i.e., @samp{=}) in the second command-line argument of -@file{centos-art.sh} script. For example, if the second command-line -argument is @option{--hello='World'}, the value of @var{ACTIONNAM} -variable would be @samp{--hello}. Using this configuration let us -deside which action to perform based on the action name passed to -@file{centos-art.sh} script as second argument. - -The @code{greet} function definition makes available two valid -greetings through @option{--hello} and @option{--bye} options. If no -one of them is provided as second command-line argument, the @samp{*} -case is evaluated instead. - -The @samp{*} case and its two lines further on should always be -present in @file{_getActions.sh} function scripts, no matter what -specific functionality you are creating. This convenction helps the -user to find out documentation about current functionality in use, -when no valid action is provided. - -The @code{greet_doHello} and @code{greet_doBye} function definitions -are the core of @code{greet} specific functionality. In such function -definitions we set what our @code{greet} function really does: to -output different kinds of greetings. - -@verbatim -function greet_doHello { - - cli_printMessage "`gettext "Hello"` $ACTIONVAL" - -} -@end verbatim - -The @code{greet_doHello} function definition is stored in -@file{greet_doHello.sh} function script. - -@verbatim -function greet_doBye { - - cli_printMessage "`gettext "Goodbye"` $ACTIONVAL" - -} -@end verbatim - -The @code{greet_doBye} function definition is stored in the -@file{greet_doBye.sh} function script. - -Both @file{greet_doHello.sh} and @file{greet_doBye.sh} function -scripts are stored inside @code{greet} function directory path (i.e. -@file{trunk/Scripts/Bash/Functions/Greet}). - -The @var{ACTIONVAL} global variable is defined in @file{cli.sh} -function script and contains the value passed after the equal sign -(i.e., @samp{=}) in the second command-line argument of -@file{centos-art.sh} script. For example, if the second command-line -argument is @option{--hello='World'}, the value of @var{ACTIONVAL} -variable would be @samp{World} without quotes. - -Let's see how @code{greet} specific functionality files are organzied -under @code{greet} function directory. To see file organization we use -the @command{tree} command: - -@verbatim -trunk/Scripts/Bash/Functions/Greet -|-- greet_doBye.sh -|-- greet_doHello.sh -|-- greet_getActions.sh -`-- greet.sh -@end verbatim - -To try the @code{greet} specific functionality we've just created, -pass the function name (i.e., @samp{greet}) as first argument to -@file{centos-art.sh} script, and any of the valid options as second -argument. Some examples are illustrated below: - -@verbatim -[centos@projects ~]$ centos-art greet --hello='World' -Hello World -[centos@projects ~]$ centos-art greet --bye='World' -Goodbye World -[centos@projects ~]$ -@end verbatim - -The word @samp{World} in the examples above can be anything. In fact, -change it to have a little fun. - -Now that we have a specific function that works as we expect, it is -time to document it. To document @code{greet} specific functionality, -we use its directory path and the @code{manual} functionality -(--- @strong{Removed}(pxref:trunk Scripts Bash Functions Manual) ---) of @file{centos-art.sh} -script, just as the following command illustrates: - -@verbatim -centos-art manual --edit=trunk/Scripts/Bash/Functions/Greet -@end verbatim - -To have a well documented function helps user to understand how your -function really works, and how it should be used. When no valid -action is passed to a function, the @file{centos-art.sh} script uses -the function documentation entry as vehicle to communicate which the -valid functions are. When no documentation entry exists for a -function, the @file{centos-art.sh} script informs that no -documentation entry exists for such function and requests user to -create it right at that time. - -Now that we have documented our function, it is time to translate its -output messages to different languages. To translate specific -functionality output messages to different languages we use the -@code{locale} functionality (--- @strong{Removed}(pxref:trunk Scripts Bash Functions -Locale) ---) of @file{centos-art.sh} script, just as the following command -illustrates: - -@verbatim -centos-art locale --edit -@end verbatim - -@quotation -@strong{Warning} To translate output messages in different languages, -your system locale information ---as in @env{LANG} environment -variable--- must be set to that locale you want to produce translated -messages for. For example, if you want to produce translated messages -for Spanish language, your system locale information must be set to -@samp{es_ES.UTF-8}, or similar, first. -@end quotation - -Well, it seems that our example is rather complete by now. - -In @code{greet} function example we've described so far, we only use -@command{cli_printMessage} global function in action specific function -definitions in order to print messages, but more interesting things -can be achieved inside action specific function definitions. For -example, if you pass a directory path as action value in second -argument, you could retrive a list of files from therein, and process -them. If the list of files turns too long or you just want to control -which files to process, you could add the third argument in the form -@option{--filter='regex'} and reduce the amount of files to process -using a regular expression pattern. - -The @code{greet} function described in this section may serve you as -an introduction to understand how specific functionalities work inside -@file{centos-art.sh} script. With some of luck this introduction will -also serve you as motivation to create your own @file{centos-art.sh} -script specific functionalities. - -By the way, the @code{greet} functionality doesn't exist inside -@file{centos-art.sh} script yet. Would you like to create it? - -@subsection Usage - -@subsubsection Global variables - -The following global variables of @file{centos-art.sh} script, are -available for you to use inside specific functions: - -@defvar TEXTDOMAIN -Default domain used to retrieve translated messages. This value is set -in @file{initFunctions.sh} and shouldn't be changed. -@end defvar - -@defvar TEXTDOMAINDIR -Default directory used to retrieve translated messages. This value is -set in @file{initFunctions.sh} and shouldn't be changed. -@end defvar - -@defvar FUNCNAM -Define function name. - -Function names associate sets of actions. There is one set of actions -for each unique function name inside @file{centos-art.sh} script. - -Dunction names are passed as first argument in @file{centos-art.sh} -command-line interface. For example, in the command @samp{centos-art -render --entry=path/to/dir --filter=regex}, the @var{ACTION} passed to -@file{centos-art.sh} script is @option{render}. - -When first argument is not provided, the @file{centos-art.sh} script -immediatly ends its execution. -@end defvar - -@defvar FUNCDIR -@end defvar - -@defvar FUNCDIRNAME -@end defvar - -@defvar FUNCSCRIPT -@end defvar - -@defvar FUNCCONFIG -@end defvar - -@defvar ACTIONNAM -Define action name. - -Each action name identifies an specific action to perform, inside an -specific function. - -Action name names aare passed as second argument in -@file{centos-art.sh} command-line interface. For example, in the -command @samp{centos-art render --entry=path/to/dir --filter=regex}, -the @var{ACTIONNAM} passed to @file{centos-art.sh} script is -@option{--entry}. - -When second argument is not provided, the @file{centos-art.sh} script -immediatly ends its execution. -@end defvar - -@defvar ACTIONVAL -Define action value. - -Action values are associated to just one action name. Action values -contain the working copy entry over which its associated action will be -performed in. Working copy entries can be files or directories inside -the working copy. -@end defvar - -@defvar REGEX -Define regular expression used as pattern to build the list of files -to process. - -By default, @var{REGEX} variable is set to @code{.+} to match all -files. - -Functions that need to build a list of files to process use the option -@option{--filter} to redefine @var{REGEX} variable default value, and -so, control the amount of files to process. -@end defvar - -@defvar ARGUMENTS -Define optional arguments. - -Optional arguments, inside @file{centos-art.sh} script, are considered -as all command-line arguments passed to @file{centos-art.sh} script, -from third argument position on. For example, in the command -@samp{centos-art render --entry=path/to/dir --filter=regex} , the -optional arguments are from @samp{--filter=regex} argument on. - -Optional arguments are parsed using @command{getopt} command through -the following base construction: - -@verbatim -# Define short options we want to support. -local ARGSS="" - -# Define long options we want to support. -local ARGSL="filter:,to:" - -# Parse arguments using getopt(1) command parser. -cli_doParseArguments - -# Reset positional parameters using output from (getopt) argument -# parser. -eval set -- "$ARGUMENTS" - -# Define action to take for each option passed. -while true; do - case "$1" in - --filter ) - REGEX="$2" - shift 2 - ;; - --to ) - TARGET="$2" - shift 2 - ;; - * ) - break - esac -done -@end verbatim - -Optional arguments provide support to command options inside -@file{centos-art.sh} script. For instance, consider the Subversion -(@command{svn}) command, where there are many options (e.g., -@option{copy}, @option{delete}, @option{move}, etc), and inside each -option there are several modifiers (e.g., @samp{--revision}, -@samp{--message}, @samp{--username}, etc.) that can be combined one -another in their short or long variants. - -The @var{ARGUMENTS} variable is used to store arguments passed from -command-line for later use inside @file{centos-art.sh} script. Storing -arguments is specially useful when we want to run a command with some -specific options from them. Consider the following command: - -@verbatim -centos-art path --copy=SOURCE --to=TARGET --message="The commit message goes here." --username='johndoe' -@end verbatim - -In the above command, the @option{--message}, and @option{--username} -options are specific to @command{svn copy} command. In such cases, -options are not interpreted by @file{centos-art.sh} script itself. -Instead, the @file{centos-art.sh} script uses @command{getopt} to -retrive them and store them in the @var{ARGUMENTS} variable for later -use, as described in the following command: - -@verbatim -# Build subversion command to duplicate locations inside the -# workstation. -eval svn copy $SOURCE $TARGET --quiet $ARGUMENTS -@end verbatim - -When @command{getopt} parses @var{ARGUMENTS}, we may use short options -(e.g., @option{-m}) or long options (e.g., @option{--message}). When -we use short options, arguments are separated by one space from the -option (e.g., @option{-m 'This is a commit message.'}). When we use -long options arguments are separated by an equal sign (@samp{=}) -(e.g., @option{--message='This is a commit message'}). - -In order for @command{getopt} to parse @var{ARGUMENTS} correctly, it -is required to provide the short and long definition of options that -will be passed or at least supported by the command performing the -final action the function script exists for. - -As convenction, inside @file{centos-art.sh} script, short option -definitions are set in the @var{ARGSS} variable; and long option -definitions are set in the @var{ARGSL} variable. - -When you define short and long options, it may be needed to define -which of these option arguments are required and which not. To define -an option argument as required, you need to set one colon @samp{:} -after the option definition (e.g., @option{-o m: -l message:}). On -the other hand, to define an option argument as not required, you need -to set two colons @samp{::} after the option definition (e.g., -@option{-o m:: -l message::}). -@end defvar - -@defvar 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. -@end defvar - -@subsubsection Global functions - -Function scripts stored directly under -@file{trunk/Scripts/Bash/Functions/} directory are used to define -global functions. Global functions can be used inside action specific -functionalities and or even be reused inside themselves. This section -provides introductory information to global functions you can use -inside @file{centos-art.sh} script. - -@defun cli_checkActionArguments -Validate action value (@var{ACTIONVAL}) variable. - -The action value variable can take one of the following values: - -@enumerate -@item Path to one directory inside the local working copy, -@item Path to one file inside the local working copy, -@end enumerate - -If another value different from that specified above is passed to -action value variable, the @file{centos-art.sh} script prints an error -message and ends script execution. -@end defun - -@defun cli_checkFiles FILE [TYPE] -Verify file existence. - -@code{cli_checkFiles} receives a @var{FILE} absolute path and performs -file verification as specified in @var{TYPE}. When @var{TYPE} is not -specified, @code{cli_checkFiles} verifies @var{FILE} existence, no -matter what kind of file it be. If @var{TYPE} is specified, use one -of the following values: - -@table @option -@item d -@itemx directory -Ends script execution if @var{FILE} is not a directory. - -When you verify directories with cli_checkFiles, if directory doesn't -exist, @file{centos-art.sh} script asks you for confirmation in order -to create that directory. If you answer positively, -@file{centos-art.sh} script creates that directory and continues -script flows normally. Otherwise, if you answer negatively, -@file{centos-art.sh} ends script execution with an error and -documentation message. - -@item f -@item regular-file -Ends script execution if @var{FILE} is not a regular file. -@item h -@itemx symbolic-link -Ends script execution if @var{FILE} is not a symbolic link. -@item x -@itemx execution -Ends script execution if @var{FILE} is not executable. -@item fh -Ends script execution if @var{FILE} is neither a regular file nor a -symbolic link. -@item fd -Ends script execution if @var{FILE} is neither a regular file nor a -directory. -@item isInWorkingCopy -Ends script execution if @var{FILE} is not inside the working copy. -@end table - -As default behaviour, if @var{FILE} passes all verifications, -@file{centos-art.sh} script continues with its normal flow. -@end defun - -@defun cli_commitRepoChanges [LOCATION] - -Syncronize changes between repository and working copy. - -The @code{cli_commitRepoChanges} function brings changes from the -central repository down to the working copy---using @command{svn -update}---, checks the working copy changes---using @command{svn -status} command---, prints status report---using both @command{svn -update} and @command{svn status} commands output, and finally, commits -recent changes from the working copy up to the repository---using -@command{svn commit} command---. - -Previous to commit the working copy changes up to the central -repository, the @code{cli_commitRepoChanges} function asks you to -verify changes---using @command{svn diff} command---, and later, -another confirmation question is shown to be sure you really want to -commit changes up to central repository. - -If @var{LOCATION} argument is not specified, the value of -@var{ACTIONVAL} variable is used as reference instead. - -@float Figure, trunk/Scripts/Bash/Functions/cli_commitRepoChanges -@verbatim ----------------------------------------------------------------------- ---> Bringing changes from the repository into the working copy ---> Checking changes in the working copy ----------------------------------------------------------------------- -Added 0 file from the repository. -Deleted 0 file from the repository. -Updated 0 file from the repository. -Conflicted 0 file from the repository. -Merged 0 file from the repository. -Modified 4 files from the working copy. -Unversioned 0 file from the working copy. -Deleted 0 file from the working copy. -Added 0 file from the working copy. ----------------------------------------------------------------------- -@end verbatim -@caption{The @code{cli_commitRepoChanges} function output.} -@end float - -Call the @code{cli_commitRepoChanges} function before or/and after -calling functions that modify files or directories inside the working -copy as you may need to. -@end defun - -@defun cli_doParseArguments -Redefine arguments (@var{ARGUMENTS}) global variable using -@command{getopt} command output. For more information about how to use -@code{cli_doParseArguments} function, see @var{ARGUMENTS} variable -description above. -@end defun - -@defun cli_doParseArgumentsReDef $@@ -Initialize/reset arguments (@var{ARGUMENTS}) global variable using -positional parameters variable (@var{$@@}) as reference. - -When we work inside function definitions, positional parameters are -reset to the last function definition positional parameters. If you -need to redefine positional parameters from one specific function, you -need to call @code{cli_doParseArgumentsReDef} with the positional -parameters variable (@var{$@@}), set as first argument, to that -specific function you want to redefine positional parameters at. -@end defun - -@defun cli_getArguments - -Initialize function name (@var{FUNCNAM}), action name -(@var{ACTIONNAM}), and action value (@var{ACTIONVAL}) global -variables, using positional parameters passed in @var{$@@} variable. - -The @code{cli_getArguments} function is called from @code{cli.sh} -function script, using @code{cli} function positional parameters -(i.e., the positional parameters passed as arguments in the -command-line) as first function argument. - -Once command-line positional parameters are accesible to -@file{centos-art.sh} script execution evironment, -@code{cli_getArguments} uses regular expression to retrive -action variables from first and second argument. The first argument -defines the value used as function name (@var{FUNCNAM}), and the -second argument defines both values used as action name -(@var{ACTIONNAM}) and action value (@var{ACTIONVAL}), respectively. - -The first argument is a word in lower case. This word specifies the -name of the functionality you want to use (e.g., @samp{render} to -render images, @samp{manual} to work on documentation, and so on.) - -The second argument has a long option style (e.g., -@samp{--option=value}). The @samp{--option} represents the action name -(@var{ACTIONNAM}), and the characters inbetween the equal sign -(@samp{=}) and the first space character, are considered as the action -value (@var{ACTIONVAL}). In order to provide action values with space -characters inbetween you need to enclose action value with quotes like -in @samp{--option='This is long value with spaces inbetween'}. -Generally, action values are used to specify paths over which the -action name acts on. - -Once action related variables (i.e., @var{FUNCNAM}, @var{ACTIONNAM}, -and @var{ACTIONVAL}) are defined and validated, -@code{cli_getArguments} shifts the positional arguments to remove the -first two arguments passed (i.e., those used to retrive action related -variables) and redefine the arguments (@var{ARGUMENTS}) global -variable with the new positional parameters information. -@end defun - -@defun cli_getFunctions -Initialize funtionalities supported by @file{centos-art.sh} script. - -Functionalities supported by @file{centos-art.sh} script are organized -in functionality directories under -@file{trunk/Scripts/Bash/Functions/} directory. Each functionality -directory stores function scripts to the functionality such directory -was created for. Function scripts contain function definitions. -Function definitions contain several commands focused on achieving one -specific task only (i.e., the one such functionality was created for). - -In order for @file{centos-art.sh} script to recognize a functionality, -such functionality needs to be stored under -@file{trunk/Scripts/Bash/Functions/} in a directory written -capitalized (i.e., the whole name is written in lowercase except the -first character which is in uppercase). The directory where one -specific functionality is stored is known as the @samp{functionality -directory}. - -Inside each functionality directory, the functionalty itself is -implemented through function scripts. Function scripts are organized -in files independently one another and written in @samp{camelCase} -format with the function name as prefix. Separation between prefix -and description is done using underscore (@samp{_}) character. - -In order for @file{centos-art.sh} script to load functionalities -correctly, function definition inside function scripts should be set -using the @samp{function} reserved word, just as in the following -example: - -@verbatim -function prefix_doSomething { - - # Do something here... - -} -@end verbatim - -The above function definition is just a convenction we use, in order -to make identification of function names easier read and automate by -@file{centos-art.sh} script initialization commands, once -@file{centos-art.sh} script determines which functionality directory -to use. Specifically, in order to initialize and export functions, -@file{centos-art.sh} script executes all function scripts inside the -functionality directory, and later @command{grep} on them using a -regular expression pattern, where the @samp{function} reserved word is -used as reference to retrive the function names and export them to -@file{centos-art.sh} script execution environment, and so, make -function definitions ---from function scripts inside the functionality -directory--- available for further calls. - -If the functionality specified in the command-line first argument -doesn't have a functionality directory, @file{centos-art.sh} script -considers the functionality provided in the command-line as invalid -functionality and immediatly stops script execution with an error -message. - -In order to keep visual consistency among function scripts, please -consider using the following function script design model as template -for your own function scripts: - -@verbatim -#!/bin/bash -# -# prefix_doSomething.sh -- This function illustrates function scripts -# design model you can use to create your own function scripts inside -# centos-art.sh script. -# -# Copyright (C) YEAR YOURFULLNAME -# -# This program is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 2 of the License, or -# (at your option) any later version. -# -# This program is distributed in the hope that it will be useful, but -# WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -# General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with this program; if not, write to the Free Software -# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 -# USA. -# -# ---------------------------------------------------------------------- -# $Id$ -# ---------------------------------------------------------------------- - -function prefix_doSomething { - - # Do something here... - -} -@end verbatim -@end defun - -@defun cli_getCountryCodes [FILTER] -Output country codes supported by @file{centos-art.sh} script. - -The @code{cli_getCountryCodes} function outputs a list with country -codes as defined in ISO3166 standard. When @var{FILTER} is provided, -@code{cli_getCountryCodes} outputs country codes that match -@var{FILTER} regular expression pattern. -@end defun - -@defun cli_getCountryName [FILTER] -Outputs country name supported by @file{centos-art.sh} script. - -The @code{cli_getCountryName} function reads one language locale code -in the format LL_CC and outputs the name of its related country as in -ISO3166. If filter is specified, @code{cli_getCountryName} returns the -country name that matches the locale code specified in @var{FILTER}, -exactly. -@end defun - -@defun cli_getCurrentLocale -Output current locale used by @file{centos-art.sh} script. - -The @code{cli_getCurrentLocale} function uses @env{LANG} environment -variable to build a locale pattern that is later applied to -@code{cli_getLocales} function output in order to return the current -locale that @file{centos-art.sh} script works with. - -The current locale information, returned by -@code{cli_getCurrentLocale}, is output from more specific to less -specific. For example, if @samp{en_GB} locale exists in -@code{cli_getLocales} function output, the @samp{en_GB} locale would -take precedence before @samp{en} locale. - -Locale precedence selection is quite important in order to define the -locale type we use for message translations. For example, if -@samp{en_GB} is used, we are also saying that the common language -specification for English language (i.e., @samp{en}) is no longer -used. Instead, we are using English non-common country-specific -language specifications like @samp{en_AU}, @samp{en_BW}, @samp{en_GB}, -@samp{en_US}, etc., for message translations. - -Use @code{cli_getCurrentLocale} function to know what current locale -information to use inside @file{centos-art.sh} script. -@end defun - -@defun cli_getFilesList [LOCATION] -Output list of files to process. - -The @code{cli_getFilesList} function uses @var{LOCATION} variable as -source location to build a list of files just as specified by regular -expression (@var{REGEX}) global variable. Essentially, what the -@code{cli_getFilesList} function does is using @command{find} command -to look for files in the location (@var{LOCATION}) just as posix-egrep -regular expression (@var{REGEX}) specifies. - -If @var{LOCATION} is not specified when @code{cli_getFilesList} -function is called, the action value (@var{ACTIONVAL}) global variable -is used as location value instead. - -By default, if the regular expression (@var{REGEX}) global variable is -not redefined after its first definition in the @code{cli} function, -all files that match default regular expression value (i.e., -@samp{.+}) will be added to the list of files to process. Otherwise, -if you redefine the regular expression global variable after its first -definition in the @code{cli} function and before calling -@code{cli_getFilesList} function, the last value you specifed is used -instead. - -When you need to customize the regular expression (@var{REGEX}) global -variable value inside a function, do not redefine the global variable -(at least you be absolutly convinced you need to). Instead, set the -regular expression global variable as @samp{local} to the function you -need a customized regular expression value for. If we don't redefine -the regular expression global variable as local to the function, or -use another name for the regular expression variable (which is not -very convenient in order to keep the amount of names to remember low), -you may experiment undesired concantenation issues that make your -regular expression to be something different from that you expect them -to be, specially if the function where you are doing the variable -redefinition is called several times during the same script execution. - -As result, the @code{cli_getFilesList} re-defines the value of -@var{FILES} variable with the list of files the @command{find} command -returned. As example, consider the following construction: - -@verbatim -function prefix_doSomething { - - # Initialize the list of files to process. - local FILES='' - - # Initialize location. - local LOCATION=/home/centos/artwork/trunk/Identity/Themes/Models/Default - - # Re-define regular expression to match scalable vector graphic - # files only. Note how we use the global value of REGEX to build a - # new local REGEX value here. - local REGEX="${REGEX}.*\.(svgz|svg)" - - # Redefine list of files to process. - cli_getFilesList $LOCATION - - # Process list of files. - for FILE in $FILES;do - cli_printMessages "$FILE" 'AsResponseLine' - # Do something else here on... - done - -} -@end verbatim - -@end defun - -@defun cli_getLangCodes [FILTER] -Outputs language codes supported by @file{centos-art.sh} script. - -@code{cli_getLangCodes} function outputs a list of language codes as -defined in ISO639 standard. When @var{FILTER} is provided, -@code{cli_getLangCodes} outputs language codes that match @var{FILTER} -regular expression pattern. -@end defun - -@defun cli_getLangName [FILTER] -Outputs language names supported by @file{centos-art.sh} script. - -@code{cli_getLangName} function reads one language locale code in the -format LL_CC and outputs the language related name as in ISO639. If -filter is specified, @code{cli_getLangName} returns the language name -that matches the locale code specified in @var{FILTER}, exactly. -@end defun - -@defun cli_getLocales -Output locale codes supported by @file{centos-art.sh} script. - -Occasionally, you use @code{cli_getLocales} function to add locale -information in non-common country-specific language (@samp{LL_CC}) -format for those languages (e.g., @samp{bn_IN}, @samp{pt_BR}, etc.) -which locale differences cannot be solved using common language -specifications (@samp{LL}) into one unique common locale specification -(e.g., @samp{bn}, @samp{pt}, etc.). -@end defun - -@defun cli_getRepoName NAME TYPE -Sanitate file names. - -Inside @file{centos-art.sh} script, specific functionalities rely both -in @code{cli_getRepoName} and repository file system organization to -achieve their goals. Consider @code{cli_getRepoName} function as -central place to manage file name convenctions for other functions -inside @file{centos-art.sh} script. - -@quotation -@strong{Important} @code{cli_getRepoName} function doesn't verify file -or directory existence, for that purpose use @code{cli_checkFiles} -function instead. -@end quotation - -The @var{NAME} variable contains the file name or directory name you -want to sanitate. - -The @var{TYPE} variable specifies what type of sanitation you want to -perform on @var{NAME}. The @var{TYPE} can be one of the following -values: - -@table @option -@item d -@itemx directory -Sanitate directory @var{NAME}s. -@item f -@item regular-file -Sanitate regular file @var{NAME}s. -@end table - -Use @code{cli_getRepoName} function to sanitate file names and -directory names before their utilization. - -Use @code{cli_getRepoName} when you need to change file name -convenctions inside @file{centos-art.sh} script. - -When we change file name convenctions inside @code{cli_getRepoName} -what we are really changing is the way functions interpret repository -file system organization. Notice that when we change a file name -(e.g., a function name), it is necessary to update all files where -such file name is placed on. This may require a massive substitution -inside the repository, each time we change name convenctions in the -repository (--- @strong{Removed}(pxref:trunk Scripts Bash Functions Path) ---, for more -information). -@end defun - -@defun cli_getRepoStatus [LOCATION] -Request repository status. - -This function requests the status of a @var{LOCATION} inside the -working copy using the @command{svn status} command and returns the -first character in the output line, just as described in @command{svn -help status}. If @var{LOCATION} is not a regular file or a directory, -inside the working copy, the @file{centos-art.sh} script prints a -message and ends its execution. - -Use this function to perform verifications based a repository -@var{LOCATION} status. -@end defun - -@defun cli_getTemporalFile @var{NAME} -Output absolute path to temporal file @var{NAME}. - -The @code{cli_getTemporalFile} function uses @file{/tmp} directory as -source location to store temporal files, the @file{centos-art.sh} -script name, and a random identification string to let you run more -than one @file{centos-art.sh} script simultaneously on the same user -session. For example, due the following temporal file defintion: - -@verbatim -cli_getTemporalFile $FILE -@end verbatim - -If @var{FILE} name is @file{instance.svg} and the unique random string -is @samp{f16f7b51-ac12-4b7f-9e66-72df847f12de}, the final temporal -file, built from previous temporal file definition, would be: - -@verbatim -/tmp/centos-art.sh-f16f7b51-ac12-4b7f-9e66-72df847f12de-instance.svg -@end verbatim - -When you use the @code{cli_getTemporalFile} function to create -temporal files, be sure to remove temporal files created once you've -ended up with them. For example, consider the following construction: - -@verbatim -for FILE in $FILES;do - - # Initialize temporal instance of file. - INSTANCE=$(cli_getTemporalFile $FILE) - - # Do something ... - - # Remove temporal instance of file. - if [[ -f $INSTANCE ]];then - rm $INSTANCE - fi - -done -@end verbatim - -Use the @code{cli_getTemporalFile} function whenever you need to -create temporal files inside @file{centos-art.sh} script. -@end defun - -@defun cli_getThemeName -Output theme name. - -In order for @code{cli_getThemeName} function to extract theme name -correctly, the @var{ACTIONVAL} variable must contain a directory path -under @file{trunk/Identity/Themes/Motifs/} directory structure. -Otherwise, @code{cli_getThemeName} returns an empty string. -@end defun - -@defun cli_printMessage MESSAGE [FORMAT] -Define standard output message definition supported by -@file{centos-art.sh} script. - -When @var{FORMAT} is not specified, @code{cli_printMessage} outputs -information just as it was passed in @var{MESSAGE} variable. -Otherwise, @var{FORMAT} can take one of the following values: - -@table @option -@item AsHeadingLine -To print heading messages. -@verbatim ----------------------------------------------------------------------- -$MESSAGE ----------------------------------------------------------------------- -@end verbatim - -@item AsWarningLine -To print warning messages. -@verbatim ----------------------------------------------------------------------- -WARNING: $MESSAGE ----------------------------------------------------------------------- -@end verbatim - -@item AsNoteLine -To print note messages. -@verbatim ----------------------------------------------------------------------- -NOTE: $MESSAGE ----------------------------------------------------------------------- -@end verbatim - -@item AsUpdatingLine -To print @samp{Updating} messages on two-columns format. -@verbatim -Updating $MESSAGE -@end verbatim - -@item AsRemovingLine -To print @samp{Removing} messages on two-columns format. -@verbatim -Removing $MESSAGE -@end verbatim - -@item AsCheckingLine -To print @samp{Checking} messages on two-columns format. -@verbatim -Checking $MESSAGE -@end verbatim - -@item AsCreatingLine -To print @samp{Creating} messages on two-columns format. -@verbatim -Creating $MESSAGE -@end verbatim - -@item AsSavedAsLine -To print @samp{Saved as} messages on two-columns format. -@verbatim -Saved as $MESSAGE -@end verbatim - -@item AsLinkToLine -To print @samp{Linked to} messages on two-columns format. -@verbatim -Linked to $MESSAGE -@end verbatim - -@item AsMovedToLine -To print @samp{Moved to} messages on two-columns format. -@verbatim -Moved to $MESSAGE -@end verbatim - -@item AsTranslationLine -To print @samp{Translation} messages on two-columns format. -@verbatim -Translation $MESSAGE -@end verbatim - -@item AsConfigurationLine -To print @samp{Configuration} messages on two-columns format. -@verbatim -Configuration $MESSAGE -@end verbatim - -@item AsResponseLine -To print response messages on one-column format. -@verbatim ---> $MESSAGE -@end verbatim - -@item AsRequestLine -To print request messages on one-column format. Request messages -output messages with one colon (@samp{:}) and without trailing newline -(@samp{\n}) at message end. -@verbatim -$MESSAGE: -@end verbatim - -@item AsYesOrNoRequestLine -To print @samp{yes or no} request messages on one-column format. If -something different from @samp{y} is answered (when using -@code{en_US.UTF-8} locale), script execution ends immediatly. - -@verbatim -$MESSAGE [y/N]: -@end verbatim - -When we use @file{centos-art.sh} script in a locale different from -@code{en_US.UTF-8}, confirmation answer may be different from -@samp{y}. For example, if you use @code{es_ES.UTF-8} locale, the -confirmation question would look like: - -@verbatim -$MESSAGE [s/N]: -@end verbatim - -and the confirmation answer would be @samp{s}, as it is on Spanish -@samp{sí} word. - -Definition of which confirmation word to use is set on translation -messages for your specific locale information. --- @strong{Removed}(xref:trunk Scripts -Bash Functions Locale) ---, for more information about locale-specific -translation messages. - -@item AsToKnowMoreLine -To standardize @samp{to know more, run the following command:} -messages. When the @option{AsToKnowMoreLine} option is used, the -@var{MESSAGE} value should be set to @code{"$(caller)"}. @code{caller} -is a Bash builtin that returns the context of the current subroutine -call. @option{AsToKnowMoreLine} option uses @code{caller} builtin -output to build documentation entries dynamically. - -@verbatim ----------------------------------------------------------------------- -To know more, run the following command: -centos-art manual --read='path/to/dir' ----------------------------------------------------------------------- -@end verbatim - -Use @option{AsToKnowMoreLine} option after errors and for intentional -script termination. - -@item AsRegularLine -To standardize regular messages on one-column format. - -When @var{MESSAGE} contains a colon inside (e.g., @samp{description: -message}), the @code{cli_printMessage} function outputs @var{MESSAGE} -on two-columns format. -@end table - -Use @code{cli_printMessage} function whenever you need to output -information from @file{centos-art.sh} script. - -@quotation -@strong{Tip} To improve two-columns format, change the following file: -@verbatim -trunk/Scripts/Bash/Styles/output_forTwoColumns.awk -@end verbatim -@end quotation -@end defun - -@subsubsection Specific functions - -The following specific functions of @file{centos-art.sh} script, are -available for you to use: - -@menu -@comment --- Removed(* trunk Scripts Bash Functions Html::) --- -@comment --- Removed(* trunk Scripts Bash Functions Locale::) --- -@comment --- Removed(* trunk Scripts Bash Functions Manual::) --- -@comment --- Removed(* trunk Scripts Bash Functions Path::) --- -@comment --- Removed(* trunk Scripts Bash Functions Render::) --- -@comment --- Removed(* trunk Scripts Bash Functions Render Config::) --- -@comment --- Removed(* trunk Scripts Bash Functions Shell::) --- -@comment --- Removed(* trunk Scripts Bash Functions Svg::) --- -@comment --- Removed(* trunk Scripts Bash Functions Verify::) --- -@end menu - -@subsection See also - -@menu -* trunk Scripts Bash:: -@comment --- Removed(* trunk Scripts Bash Locale::) --- -@end menu diff --git a/Manuals/Filesystem/trunk/Scripts/Bash/centos-art/Functions/Help.texi b/Manuals/Filesystem/trunk/Scripts/Bash/centos-art/Functions/Help.texi deleted file mode 100644 index fb39647..0000000 --- a/Manuals/Filesystem/trunk/Scripts/Bash/centos-art/Functions/Help.texi +++ /dev/null @@ -1,22 +0,0 @@ -@subsection Goals - -@itemize -@item ... -@end itemize - -@subsection Description - -@itemize -@item ... -@end itemize - -@subsection Usage - -@itemize -@item ... -@end itemize - -@subsection See also - -@menu -@end menu diff --git a/Manuals/Filesystem/trunk/Scripts/Bash/centos-art/Functions/Html.texi b/Manuals/Filesystem/trunk/Scripts/Bash/centos-art/Functions/Html.texi deleted file mode 100644 index fb39647..0000000 --- a/Manuals/Filesystem/trunk/Scripts/Bash/centos-art/Functions/Html.texi +++ /dev/null @@ -1,22 +0,0 @@ -@subsection Goals - -@itemize -@item ... -@end itemize - -@subsection Description - -@itemize -@item ... -@end itemize - -@subsection Usage - -@itemize -@item ... -@end itemize - -@subsection See also - -@menu -@end menu diff --git a/Manuals/Filesystem/trunk/Scripts/Bash/centos-art/Functions/Locale.texi b/Manuals/Filesystem/trunk/Scripts/Bash/centos-art/Functions/Locale.texi deleted file mode 100644 index bf264c9..0000000 --- a/Manuals/Filesystem/trunk/Scripts/Bash/centos-art/Functions/Locale.texi +++ /dev/null @@ -1,85 +0,0 @@ -@subsection Goals - -@itemize -@item ... -@end itemize - -@subsection Description - -This command looks for @samp{.sh} files inside Bash directory and -extracts translatable strings from files, using @command{xgettext} -command, in order to create a portable object template -(@file{centos-art.sh.pot}) file for them. - -With the @file{centos-art.sh.pot} file up to date, the -@command{centos-art} command removes the temporal list of files sotred -inside @file{/tmp} directory and checks the current language of your -user's session to create a portable object file for it, in the -location @file{$CLI_LANG/$CLI_LANG.po}. - -The @var{CLI_LANG} variable discribes the locale language used to -output messages inside @command{centos-art} command. The locale -language used inside @command{centos-art} command is taken from the -@env{LANG} environment variable. The @var{CLI_LANG} variable has the -@samp{LL_CC} format, where @samp{LL} is a language code from the -ISO-639 standard, and @samp{CC} a country code from the ISO-3166 -standard. - -The @env{LANG} environment variable is set when you do log in to your -system. If you are using a graphical session, change language to your -native language and do login. That would set and exoprt the @env{LANG} -environment variable to the correct value. On the other side, if you -are using a text session edit your @file{~/.bash_profile} file to set -and export the @env{LANG} environment variable to your native locale -as defines the @command{locale -a} command output; do logout, and do -login again. - -At this point, the @env{LANG} environment variable has the appropriate -value you need, in order to translate @command{centos-art.sh} messages -to your native language (the one set in @env{LANG} environment -variable). - -With the @file{$CLI_LANG/$CLI_LANG.po} file up to date, the -@command{centos-art} opens it for you to update translation strings. -The @command{centos-art} command uses the value of @var{EDITOR} -environment variable to determine your favorite text editor. If no -value is defined on @var{EDITOR}, the @file{/usr/bin/vim} text editor -is used as default. - -When you finishd PO file edition and quit text editor, the -@command{centos-art} command creates the related machine object in the -location @file{$CLI_LANG/LC_MESSAGES/$TEXTDOMAIN.mo}. - -At this point, all translations you made in the PO file should be -available to your language when runing @command{centos-art.sh} script. - -In order to make the @command{centos-art.sh} internationalization, the -@command{centos-art.sh} script was modified as described in the -@command{gettext} info documentation (@command{info gettext}). You -can find such modifications in the following files: - -@itemize -@item @file{trunk/Scripts/Bash/initFunctions.sh} -@item @file{trunk/Scripts/Bash/Functions/Help/cli_localeMessages.sh} -@item @file{trunk/Scripts/Bash/Functions/Help/cli_localeMessagesStatus.sh} -@end itemize - -@itemize -@item ... -@end itemize - -@subsection Usage - -@table @samp -@item centos-art locale --edit -Use this command to translate command-line interface output messages -in the current system locale you are using (as specified in @env{LANG} -environment variable). -@item centos-art locale --list -Use this command to see the command-line interface locale report. -@end table - -@subsection See also - -@menu -@end menu diff --git a/Manuals/Filesystem/trunk/Scripts/Bash/centos-art/Functions/Manual.texi b/Manuals/Filesystem/trunk/Scripts/Bash/centos-art/Functions/Manual.texi deleted file mode 100644 index fb39647..0000000 --- a/Manuals/Filesystem/trunk/Scripts/Bash/centos-art/Functions/Manual.texi +++ /dev/null @@ -1,22 +0,0 @@ -@subsection Goals - -@itemize -@item ... -@end itemize - -@subsection Description - -@itemize -@item ... -@end itemize - -@subsection Usage - -@itemize -@item ... -@end itemize - -@subsection See also - -@menu -@end menu diff --git a/Manuals/Filesystem/trunk/Scripts/Bash/centos-art/Functions/Path.texi b/Manuals/Filesystem/trunk/Scripts/Bash/centos-art/Functions/Path.texi deleted file mode 100644 index a7c6c55..0000000 --- a/Manuals/Filesystem/trunk/Scripts/Bash/centos-art/Functions/Path.texi +++ /dev/null @@ -1,327 +0,0 @@ -@subsection Goals - -This section exists to organize files related to @code{path} -functiontionality. The @code{path} functionality standardizes -movement, syncronization, branching, tagging, and general file -maintainance inside the repository. - -@subsection Description - -@emph{''CentOS like trees, has roots, trunk, branches, leaves and -flowers. Day by day they work together in freedom, ruled by the laws -of nature and open standards, to show the beauty of its existence.''} - -@subsubsection Repository layout - -The repository layout describes organization of files and directories -inside the repository. The repository layout provides the standard -backend required for automation scripts to work correctly. If such -layout changes unexpectedly, automation scripts may confuse themselves -and stop doing what we expect from them to do. - -As convenction, inside CentOS Artwork Repository, we organize files -and directories related to CentOS corporate visual identity under -three top level directories named: @file{trunk/}, @file{branches/}, -and @file{tags/}. - -The @file{trunk/} directory (@pxref{trunk}) organizes the main -development line of CentOS corporate visual identity. Inside -@file{trunk/} directory structure, the CentOS corporate visual -identity concepts are implemented using directories. There is one -directory level for each relevant concept inside the repository. The -@file{trunk/} directory structure is mainly used to perform -development tasks related to CentOS corporate visual identity. - -The @file{branches/} directory (@pxref{branches}) oranizes parallel -development lines to @file{trunk/} directory. The @file{branches/} -directory is used to set points in time where develpment lines are -devided one from another taking separte and idependent lives that -share a common past from the point they were devided on. The -@file{branches/} directory is mainly used to perform quality assurance -tasks related to CentOS corporate visual identity. - -The @file{tags/} directory (@pxref{tags}) organizes parallel frozen -lines to @file{branches/} directory. The parallel frozen lines are -immutable, nothing change inside them once they has been created. The -@file{tags/} directory is mainly used to publish final releases of -CentOS corporate visual identity. - -The CentOS Artwork Repository layout is firmly grounded on a -Subversion base. Subversion (@url{http://subversion.tigris.org}) is a -version control system, which allows you to keep old versions of files -and directories (usually source code), keep a log of who, when, and -why changes occurred, etc., like CVS, RCS or SCCS. Subversion keeps a -single copy of the master sources. This copy is called the source -``repository''; it contains all the information to permit extracting -previous versions of those files at any time. - -@subsubsection Repository name convenctions - -Repository name convenctions help us to maintain consistency of names -inside the repository. - -Repository name convenctions are applied to files and directories -inside the repository layout. As convenction, inside the repository -layout, file names are all written in lowercase -(@samp{01-welcome.png}, @samp{splash.png}, @samp{anaconda_header.png}, -etc.) and directory names are all written capitalized (e.g., -@samp{Identity}, @samp{Themes}, @samp{Motifs}, @samp{TreeFlower}, -etc.). - -Repository name convenctions are implemented inside the -@code{cli_getRepoName} function of @file{centos-art.sh} script. With -@code{cli_getRepoName} function we reduce the amount of commands and -convenctions to remember, concentrating them in just one single place -to look for fixes and improvements. - -@subsubsection Repository work flow - -Repository work flow describes the steps and time intervals used to -produce CentOS corporate visual identity inside CentOS Artwork -Repository. - -To illustrate repository work flow let's consider themes' development -cycle. - -Initially, we start working themes on their trunk development line -(e.g., @file{trunk/Identity/Themes/Motifs/TreeFlower/}), here we -organize information that cannot be produced automatically (i.e., -background images, concepts, color information, screenshots, etc.). - -Later, when theme trunk development line is considered ``ready'' for -implementation (e.g., all required backgrounds have been designed), -we create a branch for it (e.g., -@file{branches/Identity/Themes/Motifs/TreeFlower/1/}). Once the -branch has been created, we forget that branch and continue working -the trunk development line while others (e.g., an artwork quality -assurance team) test the new branch for tunning it up. - -Once the branch has been tunned up, and considered ``ready'' for -release, it is freezed under @file{tags/} directory (e.g., -@file{tags/Identity/Themes/Motifs/TreeFower/1.0/}) for packagers, -webmasters, promoters, and anyone who needs images from that CentOS -theme the tag was created for. - -Both branches and tags, inside CentOS Artwork Repository, use -numerical values to identify themselves under the same location. -Branches start at one (i.e., @samp{1}) and increment one unit for each -branch created from the same trunk development line. Tags start at -zero (i.e., @samp{0}) and increment one unit for each tag created from -the same branch development line. - -@quotation -@strong{Convenction} Do not freeze trunk development lines using tags -directly. If you think you need to freeze a trunk development line, -create a branch for it and then freeze that branch instead. -@end quotation - -The trunk development line may introduce problems we cannot see -immediatly. Certainly, the high changable nature of trunk development -line complicates finding and fixing such problems. On the other hand, -the branched development lines provide a more predictable area where -only fixes/corrections to current content are commited up to -repository. - -If others find and fix bugs inside the branched development line, we -could merge such changes/experiences back to trunk development line -(not visversa) in order for future branches, created from trunk, to -benefit. - -Time intervals used to create branches and tags may vary, just as -different needs may arrive. For example, consider the release schema -of CentOS distribution: one major release every 2 years, security -updates every 6 months, support for 7 years long. Each time a CentOS -distribution is released, specially if it is a major release, there is -a theme need in order to cover CentOS distribution artwork -requirements. At this point, is where CentOS Artwork Repository comes -up to scene. - -Before releasing a new major release of CentOS distribution we create -a branch for one of several theme development lines available inside -the CentOS Artwork Repository, perform quality assurance on it, and -later, freeze that branch using tags. Once a the theme branch has been -frozen (under @file{tags/} directory), CentOS Packagers (the persons -whom build CentOS distribution) can use that frozen branch as source -location to fulfill CentOS distribution artwork needs. The same -applies to CentOS Webmasters (the persons whom build CentOS websites), -and any other visual manifestation required by the project. - -@subsubsection Parallel directories - -Inside CentOS Artwork Repository, parallel directories are simple -directory entries built from a common parent directory and placed in a -location different to that, the common parent directory is placed on. -Parallel directories are useful to create branches, tags, -translations, documentation, pre-rendering configuration script, and -similar directory structures. - -Parallel directories take their structure from one unique parent -directory. Inside CentOS Artwork Repository, this unique parent -directory is under @file{trunk/Identity} location. The -@file{trunk/Identity} location must be considered the reference for -whatever information you plan to create inside the repository. - -In some circumstances, parallel directories may be created removing -uncommon information from their paths. Uncommon path information -refers to those directory levels in the path which are not common for -other parallel directories. For example, when rendering -@file{trunk/Identity/Themes/Motifs/TreeFlower/Distro} directory -structure, the @file{centos-art.sh} script removes the -@file{Motifs/TreeFlower/} directory levels from path, in order to -build the parallel directory used to retrived translations, and -pre-rendering configuration scripts required by @code{render} -functionality. - -Another example of parallel directory is the documentation structure -created by @code{manual} functionality. This time, -@file{centos-art.sh} script uses parallel directory information with -uncommon directory levels to build the documentation entry required by -Texinfo documentation system, inside the repository. - -Othertimes, parallel directories may add uncommon information to their -paths. This is the case we use to create branches and tags. When we -create branches and tags, a numerical identifier is added to parallel -directory structure path. The place where the numerical identifier is -set on is relevant to corporate visual identity structure and should -be carefully considered where it will be. - -When one parent directory changes, all their related parallel -directories need to be changed too. This is required in order for -parallel directories to retain their relation with the parent -directory structure. In the other hand, parallel directories should -never be modified under no reason but to satisfy the relation to their -parent directory structure. Liberal change of parallel directories -may suppresses the conceptual idea they were initially created for; -and certainly, things may stop working the way they should do. - -@subsubsection Syncronizing path information - -Parallel directories are very useful to keep repository organized but -introduce some complications. For instance, consider what would -happen to functionalities like @code{manual} (@samp{trunk Scripts Bash -Functions Manual}) that rely on parent directory structures to create -documentation entries (using parallel directory structures) if one of -those parent directory structures suddenly changes after the -documentation entry has been already created for it? - -In such cases, functionalities like @code{manual} may confuse -themselves if path information is not updated to reflect the relation -with its parent directory. Such functionalities work with parent -directory structure as reference; if a parent directory changes, the -functionalities dont't even note it because they work with the last -parent directory structure available in the repository, no matter what -it is. - -In the specific case of documentation (the @code{manual} -functionality), the problem mentioned above provokes that older parent -directories, already documented, remain inside documentation directory -structures as long as you get your hands into the documentation -directory structure (@file{trunk/Manuals}) and change what must be -changed to match the new parent directory structure. - -There is no immediate way for @code{manual}, and similar -functionalities that use parent directories as reference, to know when -and how directory movements take place inside the repository. Such -information is available only when the file movement itself takes -place inside the repository. So, is there, at the moment of moving -files, when we need to syncronize parallel directories with their -unique parent directory structure. - -@quotation -@strong{Warning} There is not support for URL reference inside -@file{centos-art.sh} script. The @file{centos-art.sh} script is -designed to work with local files inside the working copy only. -@end quotation - -As CentOS Artwork Repository is built over a version control system, -file movements inside the repository are considered repository -changes. In order for these repository changes to be versioned, we -need to, firstly, add changes into the version control system, commit -them, and later, perform movement actions using version control system -commands. This configuration makes possible for everyone to know about -changes details inside the repository; and if needed, revert or update -them back to a previous revision. - -Finally, once all path information has been corrected, it is time to -take care of information inside the files. For instance, considere -what would happen if you make a reference to a documentation node, and -later the documentation node you refere to is deleted. That would make -Texinfo to produce error messages at export time. So, the -@file{centos-art.sh} script needs to know when such changes happen, in -a way they could be noted and handled without producing errors. - -@subsubsection What is the right place to store it? - -Occasionly, you may find that new corporate visual identity components -need to be added to the repository. If that is your case, the first -question you need to ask yourself, before start to create directories -blindly all over, is: What is the right place to store it? - -The CentOS Community different free support vains (see: -@url{http://wiki.centos.org/GettingHelp}) are the best place to find -answers to your question, but going there with hands empty is not good -idea. It may give the impression you don't really care about. Instead, -consider the following suggestions to find your own comprehension and -so, make your propositions based on it. - -When we are looking for the correct place to store new files, to bear -in mind the corporate visual identity structure used inside the CentOS -Artwork Repository (@pxref{trunk Identity}) would be probaly the best -advice we could offer, the rest is just matter of choosing appropriate -names. To illustrate this desition process let's consider the -@file{trunk/Identity/Themes/Motifs/TreeFlower} directory as example. -It is the trunk development line of @emph{TreeFlower} artistic motif. -Artistic motifs are considered part of themes, which in turn are -considered part of CentOS corporate visual identity. - -When building parent directory structures, you may find that reaching -an acceptable location may take some time, and as it uses to happen -most of time; once you've find it, that may be not a definite -solution. There are many concepts that you need to play with, in -order to find a result that match the conceptual idea you try to -implement in the new directory location. To know which these concepts -are, split the location in words and read its documentation entry from -less specific to more specific. - -For example, the @file{trunk/Identity/Themes/Motifs/TreeFlower} -location evolved through several months of contant work and there is -no certain it won't change in the future, even it fixes quite well the -concept we are trying to implement. The concepts used in -@file{trunk/Identity/Themes/Distro/Motifs/TreeFlower} location are -described in the following commands, respectively: - -@verbatim -centos-art manual --read=turnk/ -centos-art manual --read=turnk/Identity/ -centos-art manual --read=turnk/Identity/Themes/ -centos-art manual --read=turnk/Identity/Themes/Motifs/ -centos-art manual --read=turnk/Identity/Themes/Motifs/TreeFlower/ -@end verbatim - -Other location concepts can be found similary as we did above, just -change the location we used above by the one you are trying to know -concepts for. - -@subsection Usage - -@table @command -@item centos-art path --copy='SRC' --to='DST' - -Copy @option{SRC} to @option{DST} and schedule @option{DST} for -addition (with history). In this command, @file{SRC} and @file{DST} -are both working copy (WC) entries. - -@item centos-art path --delete='SRC' - -Delete @option{DST}. In order for this command to work the file or -directory you intend to delete should be under version control first. -In this command, @file{SRC} is a working copy (WC) entry. - -@end table - -@subsection See also - -@menu -* trunk Scripts Bash:: -@comment --- Removed(* trunk Scripts Bash Functions::) --- -@end menu diff --git a/Manuals/Filesystem/trunk/Scripts/Bash/centos-art/Functions/Render.texi b/Manuals/Filesystem/trunk/Scripts/Bash/centos-art/Functions/Render.texi deleted file mode 100644 index 7dfe2c5..0000000 --- a/Manuals/Filesystem/trunk/Scripts/Bash/centos-art/Functions/Render.texi +++ /dev/null @@ -1,736 +0,0 @@ -The @code{render} functionality exists to produce both identity and -translation files on different levels of information (i.e., different -languages, release numbers, architectures, etc.). - -The @code{render} functionality relies on ``renderable directory -structures'' to produce files. Renderable directory structures can be -either ``identity directory structures'' or ``translation directory -structures'' with special directories inside. - -@subsection Renderable identity directory structures - -Renderable identity directory structures are the starting point of -identity rendition. Whenever we want to render a component of CentOS -corporate visual identity, we need to point @file{centos-art.sh} to a -renderable identity directory structure. If such renderable identity -directory structure doesn't exist, then it is good time to create it. - -Inside the working copy, one renderable identity directory structures -represents one visual manifestation of CentOS corporate visual -identity, or said differently, each visual manifestation of CentOS -corporate visual identity should have one renderable identity -directory structure. - -Inside renderable identity directory structures, @file{centos-art.sh} -can render both image-based and text-based files. Specification of -whether a renderable identity directory structure produces image-based -or text-based content is a configuration action that takes place in -the pre-rendition configuration script of that renderable identity -directory structure. - -Inside renderable identity directory structures, content production is -organized in different configurations. A content production -configuration is a unique combination of the components that make an -identity directory structure renderable. One content production -configuration does one thing only (e.g., to produce untranslated -images), but it can be extended (e.g., adding translation files) to -achieve different needs (e.g., to produce translated images). - -@subsubsection Design template without translation - -The design template without translation configuration is based on a -renderable identity directory structure with an empty translation -directory structure. In this configuration, one design template -produces one untranslated file. Both design templates and final -untranslated files share the same file name, but they differ one -another in file-type and file-extension. - -For example, to produce images without translations (there is no much -use in producing text-based files without translations), consider the -following configuration: - -@table @strong -@item One renderable identity directory structure: - -In this example we used @file{Identity/Path/To/Dir} as the identity -component we want to produce untranslated images for. Identity -components can be either under @file{trunk/} or @file{branches/} -directory structure. - -The identity component (i.e., @file{Identity/Path/To/Dir}, in this -case) is also the bond component we use to connect the identity -directory structures with their respective auxiliar directories (i.e., -translation directory structres and pre-rendition configuration -structures). The bond component is the path convenction that -@file{centos-art.sh} uses to know where to look for related -translations, configuration scripts and whatever auxiliar thing a -renderable directory structure may need to have. - -@verbatim - | The bond component - |----------------->| -trunk/Identity/Path/To/Dir <-- Renderable identity directory structure. -|-- Tpl <-- Design template directory. -| `-- file.svg <-- Design template file. -`-- Img <-- Directory used to store final files. - `-- file.png <-- Final image-based file produced from - design template file. -@end verbatim - -Inside design template directory, design template files are based on -@acronym{SVG,Scalable Vector Graphics} and use the extension -@code{.svg}. Design template files can be organized using several -directory levels to create a simple but extensible configuration, -specially if translated images are not required. - -In order for @acronym{SVG,Scalable Vector Graphics} files to be -considered ``design template'' files, they should be placed under the -design template directory and to have set a @code{CENTOSARTWORK} -object id inside. - -The @code{CENTOSARTWORK} word itself is a convenction name we use to -define which object/design area, inside a design template, the -@file{centos-art.sh} script will use to export as -@acronym{PNG,Portable Network Graphic} image at rendition time. -Whithout such object id specification, the @file{centos-art.sh} script -cannot know what object/design area you (as designer) want to export -as @acronym{PNG,Portable Network Graphic} image file. - -@quotation -@strong{Note} At rendition time, the content of @file{Img/} directory -structure is produced by @file{centos-art.sh} automatically. -@end quotation - -When a renderable identity directory structure is configured to -produce image-based content, @file{centos-art.sh} produces -@acronym{PNG,Portable Network Graphics} files with the @code{.png} -extension. Once the base image format has been produced, it is -possible for @file{centos-art.sh} to use it in order to automatically -create other image formats that may be needed (--- @strong{Removed}(pxref:trunk Scripts -Bash Functions Render Config) ---). - -Inside the working copy, you can find an example of ``design template -without translation'' configuration at @file{trunk/Identity/Models/}. - -@xref{trunk Identity}, for more information. - -@item One translation directory structure: - -In order for an identity entry to be considered an identity renderable -directory structure, it should have a translation entry. The content -of the translation entry is relevant to determine how to process the -identity renderable directory entry. - -If the translation entry is empty (i.e., there is no file inside it), -@file{centos-art.sh} interprets the identity renderable directory -structure as a ``design templates without translation'' configuration. - -@verbatim - | The bond component - |----------------->| -trunk/Translations/Identity/Path/To/Dir -`-- (empty) -@end verbatim - -If the translation entry is not empty, @file{centos-art.sh} can -interpret the identity renderable directory structure as one of the -following configurations: ``design template with translation -(one-to-one)'' or ``design template with translation (optimized)''. -Which one of these configurations is used depends on the value -assigned to the matching list (@var{MATCHINGLIST}) variable in the -pre-rendition configuration script of the renderable identity -directory structure we are producing images for. - -If the matching list variable is empty (as it is by default), then -``design template with translation (one-to-one)'' configuration is -used. In this configuration it is required that both design templates -and translation files have the same file names. This way, @emph{one} -translation files is applied to @emph{one} design template, to produce -@emph{one} translated image. - -If the matching list variable is not empty (because you redefine it in -the pre-rendition configuration script), then ``design template with -translation (optimized)'' configuration is used instead. In this -configuration, design templates and translation files don't need to -have the same names since such name relationship between them is -specified in the matching list properly. - ---- @strong{Removed}(xref:trunk Translations) ---, for more information. - -@item One pre-rendition configuration script: - -In order to make an identity directory structure renderable, a -pre-rendition configuration script should exist for it. The -pre-rendition configuration script specifies what type of rendition -does @file{centos-art.sh} will perform over the identity directory -structure and how does it do that. - -@verbatim - | The bond component - |----------------->| -trunk/Scripts/Bash/Functions/Render/Config/Identity/Path/To/Dir -`-- render.conf.sh -@end verbatim - -In this configuration the pre-rendition configuration script -(@file{render.conf.sh}) would look like the following: - -@verbatim -function render_loadConfig { - - # Define rendition actions. - ACTIONS[0]='BASE:renderImage' - -} -@end verbatim - -Since translation directory structure is empty, @file{centos-art.sh} -assumes a ``design template without translation'' configuration to -produce untranslated images. - -To produce untranslated images, @file{centos-art.sh} takes one design -template and creates one temporal instance from it. Later, -@file{centos-art.sh} uses the temporal design template instance as -source file to export the final untranslated image. The action of -exporting images from @acronym{SVG,Scalable Vector Graphics} to -@acronym{PNG,Portable Network Graphics} is possible thanks to -Inkscape's command-line interface and the @code{CENTOSARTWORK} object -id we previously set inside design templates. - -@verbatim -centos-art.sh render --identity=trunk/Identity/Path/To/Dir -------------------------------------------------- -0 | Execute centos-art.sh on renderable identity directory structure. ---v---------------------------------------------- -trunk/Identity/Path/To/Dir/Tpl/file.svg -------------------------------------------------- -1 | Create instance from design template. ---v---------------------------------------------- -/tmp/centos-art.sh-a07e824a-5953-4c21-90ae-f5e8e9781f5f-file.svg -------------------------------------------------- -2 | Render untranslated image from design template instance. ---v---------------------------------------------- -trunk/Identity/NewDir/Img/file.png -------------------------------------------------- -3 | Remove design template instance. -@end verbatim - -Finally, when the untranslated image has been created, the temporal -design template instance is removed. At this point, -@file{centos-art.sh} takes the next design template and repeats the -whole production flow once again (design template by design template), -until all design templates be processed. - ---- @strong{Removed}(xref:trunk Scripts Bash Functions Render Config) ---, for more -information. -@end table - -@subsubsection Design template with translation (one-to-one) - -Producing untranslated images is fine in many cases, but not always. -Sometimes it is required to produce images in different languages and -that is something that untrasnlated image production cannot achieve. -However, if we fill its empty translation entry with translation files -(one for each design template) we extend the production flow from -untranslated image production to translated image production. - -In order for @file{centos-art.sh} to produce images correctly, each -design template should have one translation file and each translation -file should have one design template. Otherwise, if there is a -missing design template or a missing translation file, -@file{centos-art.sh} will not produce the final image related to the -missing component. - -In order for @file{centos-art.sh} to know which is the relation -between translation files and design templates the translation -directory structure is taken as reference. For example, the -@file{trunk/Translations/Identity/Path/To/Dir/file.sed} translation -file does match @file{trunk/Identity/Path/To/Dir/Tpl/file.svg} design -template, but it doesn't match -@file{trunk/Identity/Path/To/Dir/File.svg} or -@file{trunk/Identity/Path/To/Dir/Tpl/File.svg} or -@file{trunk/Identity/Path/To/Dir/Tpl/SubDir/file.svg} design -templates. - -The pre-rendition configuration script used to produce untranslated -images is the same we use to produce translated images. There is no -need to modify it. So, as we are using the same pre-rendition -configuration script, we can say that translated image production is -somehow an extended/improved version of untranslated image production. - -@quotation -@strong{Note} If we use no translation file in the translation entry -(i.e., an empty directory), @file{centos-art.sh} assumes the -untranslated image production. If we fill the translation entry with -translation files, @file{centos-art.sh} assumes the translated image -production. -@end quotation - -To produce final images, @file{centos-art.sh} applies one translation -file to one design template and produce a translated design template -instance. Later, @file{centos-art.sh} uses the translated template -instance to produce the translated image. Finally, when the translated -image has been produced, @file{centos-art.sh} removes the translated -design template instance. This production flow is repeated for each -translation file available in the translatio entry. - -@verbatim -centos-art.sh render --identity=trunk/Identity/Path/To/Dir -------------------------------------------------- -0 | Execute centos-art.sh on directory structure. ---v---------------------------------------------- -trunk/Translations/Identity/Path/To/Dir/file.sed -------------------------------------------------- -1 | Apply translation to design template. ---v---------------------------------------------- -trunk/Identity/Path/To/Dir/Tpl/file.svg -------------------------------------------------- -2 | Create design template instance. ---v---------------------------------------------- -/tmp/centos-art.sh-a07e824a-5953-4c21-90ae-f5e8e9781f5f-file.svg -------------------------------------------------- -3 | Render PNG image from template instance. ---v---------------------------------------------- -trunk/Identity/NewDir/Img/file.png -------------------------------------------------- -4 | Remove design template instance. -@end verbatim - -@subsubsection Design template with translation (optimized) - -Producing translated images satisfies almost all our production images -needs, but there is still a pitfall in them. In order to produce -translated images as in the ``one-to-one'' configuration describes -previously, it is required that one translation file has one design -template. That's useful in many cases, but what would happen if we -need to apply many different translation files to the same design -template? Should we have to duplicate the same design template file -for each translation file, in order to satisfy the ``one-to-one'' -relation? What if we need to assign translation files to design -templates arbitrarily? - -Certenly, that's something the ``one-to-one'' configuration cannot -handle. So, that's why we had to ``optimize'' it. The optimized -configuration consists on using a matching list (@var{MATCHINGLIST}) -variable that specifies the relationship between translation files and -design templates in an arbitrary way. Using such matching list between -translation files and design templates let us use as many assignment -combinations as translation files and design templates we are working -with. - -The @var{MATCHINGLIST} variable is set in the pre-rendition -configuration script of the component we want to produce images for. -By default, the @var{MATCHINGLIST} variable is empty which means no -matching list is used. Otherwise, if @var{MATCHINGLIST} variable has a -value different to empty value then, @file{centos-art.sh} interprets -the matching list in order to know how translation files are applied -to design templates. - -For example, consider the following configuration: - -@table @strong -@item One entry under @file{trunk/Identity/}: - -In this configuration we want to produce three images using a -paragraph-based style, controlled by @file{paragraph.svg} design -template; and one image using a list-based style, controlled by -@file{list.svg} design template. - -@verbatim -trunk/Identity/Path/To/Dir -|-- Tpl -| |-- paragraph.svg -| `-- list.svg -`-- Img - |-- 01-welcome.png - |-- 02-donate.png - |-- 03-docs.png - `-- 04-support.png -@end verbatim - -@item One entry under @file{trunk/Translations/}: - -In order to produce translated images we need to have one translation -file for each translated image we want to produce. Notice how -translation names do match final image file names, but how translation -names do not match design template names. When we use matching list -there is no need for translation files to match the names of design -templates, such name relation is set inside the matching list itself. - -@verbatim -trunk/Translations/Identity/Path/To/Dir -|-- 01-welcome.sed -|-- 02-donate.sed -|-- 03-docs.sed -`-- 04-support.sed -@end verbatim - -@item One entry under @file{trunk/trunk/Scripts/Bash/Functions/Render/Config/}: - -In order to produce different translated images using specific design -templates, we need to specify the relation between translation files -and design templates in a way that @file{centos-art.sh} could know -exactly what translation file to apply to what design template. This -relation between translation files and design templates is set using -the matching list @var{MATCHINGLIST} variable inside the pre-rendition -configuration script of the component we want to produce images for. - -@verbatim -trunk/Scripts/Bash/Functions/Render/Config/Identity/Path/To/Dir -`-- render.conf.sh -@end verbatim - -In this configuration the pre-rendition configuration script -(@file{render.conf.sh}) would look like the following: - -@verbatim -function render_loadConfig { - - # Define rendition actions. - ACTIONS[0]='BASE:renderImage' - - # Define matching list. - MATCHINGLIST="\ - paragraph.svg:\ - 01-welcome.sed\ - 02-donate.sed\ - 04-support.sed - list.svg:\ - 03-docs.sed - " - -} -@end verbatim - -As result, @file{centos-art.sh} will produce @file{01-welcome.png}, -@file{02-donate.png} and @file{04-support.png} using the -paragraph-based design template, but @file{03-docs.png} using the -list-based design template. -@end table - -@subsubsection Design template with translation (optimized+flexibility) - -In the production models we've seen so far, there are design templates -to produce untranslated images and translation files which combiend -with design templates produce translated images. That may seems like -all our needs are covered, doesn't it? Well, it @emph{almost} does. - -Generally, we use design templates to define how final images will -look like. Generally, each renderable directory structure has one -@file{Tpl/} directory where we organize design templates for that -identity component. So, we can say that there is only one unique -design template definition for each identity component; or what is the -same, said differently, identity components can be produced in one way -only, the way its own design template directory specifies. This is -not enough for theme production. It is a limitation, indeed. - -Initially, to create one theme, we created one renderable directory -structure for each theme component. When we found ourselves with many -themes, and components inside them, it was obvious that the same -design model was duplicated inside each theme. As design models were -independently one another, if we changed one theme's design model, -that change was useless to other themes. So, in order to reuse design -model changes, we unified design models into one common directory -structure. - -With design models unified in a common structure, another problem rose -up. As design models also had the visual style of theme components, -there was no difference between themes, so there was no apparent need -to have an independent theme directory structure for each different -theme. So, it was also needed to separate visual styles from design -models. - -At this point there are two independent worklines: one directory -structure to store design models (the final image characteristics -[i.e., dimensions, translation markers, etc.]) and one directory -structure to store visual styles (the final image visual style [i.e., -the image look and feel]). So, it is possible to handle both -different design models and different visual styles independtly one -another and later create combinations among them using -@file{centos-art.sh}. - -For example, consider the following configuration: - -@table @strong -@item One entry under @file{trunk/Identity/Themes/Models/}: - -The design model entry exists to organize design model files (similar -to design templates). Both design models and design templates are very -similar; they both should have the @code{CENTOSARTWORK} export id -present to identify the exportation area, translation marks, etc. -However, design models do use dynamic backgrounds inclusion while -design templates don't. - -@verbatim - THEMEMODEL | | The bond component - |<----| |--------------------->| -trunk/Identity/Themes/Models/Default/Distro/Anaconda/Progress/ -|-- paragraph.svg -`-- list.svg -@end verbatim - -Inisde design models, dynamic backgrounds are required in order for -different artistic motifs to reuse common design models. Firstly, in -order to create dynamic backgrounds inside design models, we import a -bitmap to cover design model's background and later, update design -model's path information to replace fixed values to dynamic values. - -@item One entry under @file{trunk/Identity/Themes/Motifs/}: - -The artistic motif entry defines the visual style we want to produce -images for, only. Final images (i.e., those built from combining both -design models and artistic motif backrounds) are not stored here, but -under branches directory structure. In the artistic motif entry, we -only define those images that cannot be produced automatically by -@file{centos-art.sh} (e.g., Backgrounds, Color information, -Screenshots, etc.). - -@verbatim - Artistic motif name | | Artistic motif backgrounds - |<-------| |-------->| -trunk/Identity/Themes/Motifs/TreeFlower/Backgrounds/ -|-- Img -| |-- Png -| | |-- 510x300.png -| | `-- 510x300-final.png -| `-- Jpg -| |-- 510x300.jpg -| `-- 510x300-final.jpg -|-- Tpl -| `-- 510x300.svg -`-- Xcf - `-- 510x300.xcf -@end verbatim - -@item One entry under @file{trunk/Translations/}: - -The translation entry specifies, by means of translation files, the -language-specific information we want to produce image for. When we -create the translation entry we don't use the name of neither design -model nor artistic motif, just the design model component we want to -produce images for. - -@verbatim - | The bond component - |--------------------->| -trunk/Translations/Identity/Themes/Distro/Anaconda/Progress/ -`-- 5 - |-- en - | |-- 01-welcome.sed - | |-- 02-donate.sed - | `-- 03-docs.sed - `-- es - |-- 01-welcome.sed - |-- 02-donate.sed - `-- 03-docs.sed -@end verbatim - -@item One entry under @file{trunk/Scripts/Bash/Functions/Render/Config/}: - -There is one pre-rendition configuration script for each theme -component. So, each time a theme component is rendered, its -pre-rendition configuration script is evaluated to teach -@file{centos-art.sh} how to render the component. - -@verbatim -trunk/Scripts/Bash/Functions/Render/Config/Identity/Themes/Distro/Anaconda/Progress/ -`-- render.conf.sh -@end verbatim - -In this configuration the pre-rendition configuration script -(@file{render.conf.sh}) would look like the following: - -@verbatim -function render_loadConfig { - - # Define rendition actions. - ACTIONS[0]='BASE:renderImage' - - # Define matching list. - MATCHINGLIST="\ - paragraph.svg:\ - 01-welcome.sed\ - 02-donate.sed - list.svg:\ - 03-docs.sed - " - - # Deifne theme model. - THEMEMODEL='Default' - -} -@end verbatim -@end table - -The production flow of ``optimize+flexibility'' configuration@dots{} -@subsection Renderable translation directory structures - -Translation directory structures are auxiliar structures of renderable -identity directory structures. There is one translation directory -structure for each renderable identity directory structure. Inside -translation directory structures we organize translation files used by -renderable identity directory structures that produce translated -images. Renderable identity directory structures that produce -untranslated images don't use translation files, but they do use a -translation directory structure, an empty translation directory -structure, to be precise. - -In order to aliviate production of translation file, we made -translation directory structures renderable adding a template -(@file{Tpl/}) directory structure to handle common content inside -translation files. This way, we work on translation templates and -later use @file{centos-art.sh} to produce specific translation files -(based on translation templates) for different information (e.g., -languages, release numbers, architectures, etc.). - -If for some reason, translation files get far from translation -templates and translation templates become incovenient to produce such -translation files then, care should be taken to avoid replacing the -content of translation files with the content of translation templates -when @file{centos-art.sh} is executed to produce translation files -from translation templates. - -Inside renderable translation directory structures, -@file{centos-art.sh} can produce text-based files only. - -@subsection Copying renderable directory structures - -A renderable layout is formed by design models, design images, -pre-rendition configuration scripts and translations files. This way, -when we say to duplicate rendition stuff we are saying to duplicate -these four directory structures (i.e., design models, design images, -pre-rendition configuration scripts, and related translations files). - -When we duplicate directories, inside `trunk/Identity' directory -structure, we need to be aware of renderable layout described above -and the source location used to perform the duplication action. The -source location is relevant to centos-art.sh script in order to -determine the required auxiliar information inside directory -structures that need to be copied too (otherwise we may end up with -orphan directory structures unable to be rendered, due the absence of -required information). - -In order for a renderable directory structure to be valid, the new -directory structure copied should match the following conditions: - -@enumerate -@item To have a unique directory structure under -@file{trunk/Identity}, organized by any one of the above -organizational designs above. - -@item To have a unique directory structure under -@file{trunk/Translations} to store translation files. - -@item To have a unique directory structure under -@file{trunk/Scripts/Bash/Functions/Render/Config} to set pre-rendition -configuration script. -@end enumerate - -As convenction, the @code{render_doCopy} function uses -@file{trunk/Identity} directory structure as source location. Once -the @file{trunk/Identity} directory structure has been specified and -verified, the related path information is built from it and copied -automatically to the new location specified by @var{FLAG_TO} variable. - -Design templates + No translation: - -Command: -- centos-art render --copy=trunk/Identity/Path/To/Dir --to=trunk/Identity/NewPath/To/Dir - -Sources: -- trunk/Identity/Path/To/Dir -- trunk/Translations/Identity/Path/To/Dir -- trunk/Scripts/Bash/Functions/Render/Config/Identity/Path/To/Dir - -Targets: -- trunk/Identity/NewPath/To/Dir -- trunk/Translations/Identity/NewPath/To/Dir -- trunk/Scripts/Bash/Functions/Render/Config/Identity/NewPath/To/Dir - -Renderable layout 2: - -Command: -- centos-art render --copy=trunk/Identity/Themes/Motifs/TreeFlower \ - --to=trunk/Identity/Themes/Motifs/NewPath/To/Dir - -Sources: -- trunk/Identity/Themes/Motifs/TreeFlower -- trunk/Translations/Identity/Themes -- trunk/Translations/Identity/Themes/Motifs/TreeFlower -- trunk/Scripts/Bash/Functions/Render/Config/Identity/Themes -- trunk/Scripts/Bash/Functions/Render/Config/Identity/Themes/Motifs/TreeFlower - -Targets: -- trunk/Identity/Themes/Motifs/NewPath/To/Dir -- trunk/Translations/Identity/Themes -- trunk/Translations/Identity/Themes/Motifs/NewPath/To/Dir -- trunk/Scripts/Bash/Functions/Render/Config/Identity/Themes -- trunk/Scripts/Bash/Functions/Render/Config/Identity/Themes/Motifs/NewPath/To/Dir - -Notice that design models are not included in source or target -locations. This is intentional. In ``Renderable layout 2'', design -models live by their own, they just exist, they are there, available -for any artistic motif to use. By default `Themes/Models/Default' -design model directory structure is used, but other design models -directory structures (under Themes/Models/) can be created and used -changing the value of THEMEMODEL variable inside the pre-rendition -configuration script of the artistic motif source location you want to -produce. - -Notice how translations and pre-rendition configuration scripts may -both be equal in source and target. This is because such structures -are common to all artistic motifs (the default values to use when no -specific values are provided). - -- The common directory structures are not copied or deleted. We cannot - copy a directory structure to itself. - -- The common directory structures represent the default value to use - when no specific translations and/or pre-rendition configuration - script are provided inside source location. - -- The specific directory structures, if present, are both copiable and - removable. This is, when you perform a copy or delete action from - source, that source specific auxiliar directories are transfered in - the copy action to a new location (that specified by FLAG_TO - variable). - -- When translations and/or pre-rendition configuration scripts are - found inside the source directory structure, the centos-art.sh - script loads common auxiliar directories first and later specific - auxiliar directories. This way, identity rendition of source - locations can be customized idividually over the base of common - default values. - -- The specific auxiliar directories are optional. - -- The common auxiliar directories should be present always. This is, - in order to provide the information required by render functionality - (i.e., to make it functional in the more basic level of its - existence). - -Notice how the duplication process is done from `trunk/Identity' on, -not the oposite. If you try to duplicate a translation structure (or -similar auxiliar directory structures like pre-rendition configuration -scripts), the `trunk/Identity' for that translation is not created. -This limitation is impossed by the fact that many `trunk/Identity' -directory structures may reuse/share the same translation directory -structure. We cannot delete one translation (or similar) directory -structures while a related `trunk/Identity/' directory structure is -still in need of it. - -The `render_doCopy' functionality does duplicate directory structures -directly involved in rendition process only. Once such directories -have been duplicated, the functionality stops thereat. - -@subsection Usage - -@itemize -@item ... -@end itemize - -@subsection See also - -@menu -@comment --- Removed(* trunk Scripts Bash Functions Render Config::) --- -@end menu diff --git a/Manuals/Filesystem/trunk/Scripts/Bash/centos-art/Functions/Render/Config.texi b/Manuals/Filesystem/trunk/Scripts/Bash/centos-art/Functions/Render/Config.texi deleted file mode 100644 index 3b3322b..0000000 --- a/Manuals/Filesystem/trunk/Scripts/Bash/centos-art/Functions/Render/Config.texi +++ /dev/null @@ -1,192 +0,0 @@ -@subsection Goals - -The @file{trunk/Scripts/Bash/Config} directory exists to oraganize -pre-rendering configuration scripts. - -@subsection Description - -Pre-rendering configuration scripts let you customize the way -@command{centos-art.sh} script renders identity and translation -repository entries. Pre-rendering configuration scripts are -@file{render.conf.sh} files with @command{render_loadConfig} function -definition inside. - -There is one @file{render.conf.sh} file for each pre-rendering -configuration entry. Pre-rendering configuration entries can be based -both on identity and translation repository entires. Pre-rendering -configuration entries are required for each identity entry, but not -for translation entries. - -@subsubsection The @file{render.conf.sh} identity model - -Inside CentOS Artwork Repository, we consider identity entries to all -directories under @file{trunk/Identity} directory. Identity entries can be -image-based or text-based. When you render image-based identity -entries you need to use image-based pre-rendering configuration -scripts. Likewise, when you render text-based identity entries you -need to use text-based pre-rendering configuration scripts. - -Inside identity pre-rendering configuration scripts, image-based -pre-rendering configuration scripts look like the following: - -@verbatim -#!/bin/bash - -function render_loadConfig { - - # Define rendering actions. - ACTIONS[0]='BASE:renderImage' - ACTIONS[1]='POST:renderFormats: tif xpm pdf ppm' - -} -@end verbatim - -Inside identity pre-rendering configuration scripts, text-based -pre-rendering configuration scripts look like the following: - -@verbatim -#!/bin/bash - -function render_loadConfig { - - # Define rendering actions. - ACTIONS[0]='BASE:renderText' - ACTIONS[1]='POST:formatText: --width=70 --uniform-spacing' - -} -@end verbatim - -When using identity pre-rendering configuration scripts, you can -extend both image-based and text-based pre-rendering configuration -scripts using image-based and text-based post-rendering actions, -respectively. - -@subsubsection The @file{render.conf.sh} translation model - -Translation pre-rendering configuration scripts take precedence before -default translation rendering action. Translation pre-rendering -actions are useful when default translation rendering action do not -fit itself to translation entry rendering requirements. - -@subsubsection The @file{render.conf.sh} rendering actions - -Inside both image-based and text-based identity pre-rendering -configuration scripts, we use the @samp{ACTIONS} array variable to -define the way @command{centos-art.sh} script performs identity -rendering. Identity rendering is organized by one @samp{BASE} action, -and optional @samp{POST} and @samp{LAST} rendering actions. - -The @samp{BASE} action specifies what kind of rendering does the -@command{centos-art.sh} script will perform with the files related to -the pre-rendering configuration script. The @samp{BASE} action is -required. Possible values to @samp{BASE} action are either -@samp{renderImage} or @samp{renderText} only. - -To specify the @samp{BASE} action you need to set the @samp{BASE:} -string followed by one of the possible values. For example, if you -want to render images, consider the following definition of -@samp{BASE} action: - -@verbatim -ACTIONS[0]='BASE:renderImage' -@end verbatim - -Only one @samp{BASE} action must be specified. If more than one -@samp{BASE} action is specified, the last one is used. If no -@samp{BASE} action is specified at all, an error is triggered and the -@command{centos-art.sh} script ends its execution. - -The @samp{POST} action specifies which action to apply for -each file rendered (at the rendering time). This action is optional. -You can set many different @samp{POST} actions to apply many different -actions over the same already rendered file. Possible values to -@samp{POST} action are @samp{renderFormats}, @samp{renderSyslinux}, -@samp{renderGrub}, etc. - -To specify the @samp{POST} action, you need to use set the -@samp{POST:} followed by the function name of the action you want to -perform. The exact form depends on your needs. For example, consider -the following example to produce @samp{xpm}, @samp{jpg}, and -@samp{tif} images, based on already rendered @samp{png} image, and -also organize the produced files in directories named as their own -extensions: - -@verbatim -ACTIONS[0]='BASE:renderImage' -ACTIONS[1]='POST:renderFormats: xpm jpg tif' -ACTIONS[2]='POST:groupByFormat: png xpm jpg tif' -@end verbatim - -In the previous example, file organization takes place at the moment -of rendering, just after producing the @samp{png} base file and before -going to the next file in the list of files to render. If you don't -want to organized the produced files in directories named as their own -extensions, just remove the @samp{POST:groupByFormat} action line: - -@verbatim -ACTIONS[0]='BASE:renderImage' -ACTIONS[1]='POST:renderFormats: xpm jpg tif' -@end verbatim - -The @samp{LAST} action specifies which actions to apply once the last -file in the list of files to process has been rendered. The -@samp{LAST} action is optional. Possible values for @samp{LAST} -actions may be @samp{groupByFormat}, @samp{renderGdmTgz}, etc. - -@quotation -@strong{Note} --- @strong{Removed}(xref:trunk Scripts Bash Functions Render) ---, to know more -about possible values for @samp{BASE}, @samp{POST} and @samp{LAST} -action definitions. -@end quotation - -To specify the @samp{LAST} action, you need to set the @samp{LAST:} -string followed by the function name of the action you want to -perform. For example, consider the following example if you want to -render all files first and organize them later: - -@verbatim -ACTIONS[0]='BASE:renderImage' -ACTIONS[1]='POST:renderFormats: xpm jpg tif' -ACTIONS[2]='LAST:groupByformat: png xpm jpg tif' -@end verbatim - -@subsection Usage - -Use the following commands to administer both identity and translation -pre-rendering configuration scripts: - -@table @samp - -@item centos-art config --create='path/to/dir/' - -Use this command to create @samp{path/to/dir} related pre-rendering -configuration script. - -@item centos-art config --edit='path/to/dir/' - -Use this command to edit @samp{path/to/dir} related pre-rendering -configuration script. - -@item centos-art config --read='path/to/dir/' - -Use this command to read @samp{path/to/dir} related pre-rendering -configuration script. - -@item centos-art config --remove='path/to/dir/' - -Use this command to remove @samp{path/to/dir} related pre-rendering -configuration script. - -@end table - -In the commands above, @samp{path/to/dir} refers to one renderable -directory path under @file{trunk/Identity} or -@file{trunk/Translations} structures only. - -@subsection See also - -@menu -* trunk Scripts Bash:: -@comment --- Removed(* trunk Scripts Bash Functions::) --- -@comment --- Removed(* trunk Scripts Bash Functions Render::) --- -@end menu diff --git a/Manuals/Filesystem/trunk/Scripts/Bash/centos-art/Functions/Shell.texi b/Manuals/Filesystem/trunk/Scripts/Bash/centos-art/Functions/Shell.texi deleted file mode 100644 index a5016fe..0000000 --- a/Manuals/Filesystem/trunk/Scripts/Bash/centos-art/Functions/Shell.texi +++ /dev/null @@ -1,184 +0,0 @@ -@subsection Goals - -This section exists to organize files related to @code{shell} -functionality of @file{centos-art.sh} script. - -@subsection Description - -The @code{shell} functionality of @file{centos-art.sh} script helps -you to maintain bash scripts inside repository. For example, suppose -you've created many functionalities for @file{centos-art.sh} script, -and you want to use a common copyright and license note for -consistency in all your script files. If you have a bunch of files, -doing this one by one wouldn't be a big deal. In contrast, if the -amount of files grows, updating the copyright and license note for all -of them would be a task rather tedious. The @code{shell} functionality -exists to solve maintainance tasks just as the one previously -mentioned. - -When you use @code{shell} functionality to update copyright inside -script files, it is required that your script files contain (at least) -the following top commentary structure: - -@float Figure,fig:trunk/Scripts/Bash/Functions/Shell:1 -@verbatim - 1| #!/bin/bash - 2| # - 3| # doSomething.sh -- The function description goes here. - 4| # - 5| # Copyright - 6| # - 7| # ... - 8| # - 9| # ---------------------------------------------------------------------- -10| # $Id$ -11| # ---------------------------------------------------------------------- -12| -13| function doSomething { -14| -15| } -@end verbatim -@caption{The functions script base comment structure} -@end float - -Relevant lines in the above structure are lines from 5 to 9. -Everything else in the file is left immutable. - -When you are updating copyright through @code{shell} -functionality, the @file{centos-art.sh} script replaces everything -in-between line 5 ---the first one matching @samp{^# Copyright .+$} -string--- and line 9---the first long dash separator matching @samp{^# --+$}--- with the content of copyright template instance. - -@quotation -@strong{Caution} Be sure to add the long dash separator that matches -@samp{^# -+$} regular expression @emph{before} the function -definition. Otherwise, if the @samp{Copyright} line is present but no -long dash separator exists, @file{centos-art.sh} will remove anything -in-between the @samp{Copyright} line and the end of file. This way you -may lost your function definitions entirely. -@end quotation - -The copyright template instance is created from one copyright template -stored in the @file{Config/tpl_forCopyright.sed} file. The template -instance is created once, and later removed when no longer needed. At -this moment, when template instance is created, the -@file{centos-art.sh} script takes advantage of automation in order to -set copyright full name and date dynamically. - -When you use @code{shell} functionality to update copyright, the first -thing @file{shell} functionality does is requesting copyright -information to user, and later, if values were left empty (i.e., no -value was typed before pressing @key{RET} key), the @file{shell} -functionality uses its own default values. - -When @code{shell} functionality uses its own default values, the final -copyright note looks like the following: - -@float Figure,fig:trunk/Scripts/Bash/Functions/Shell:2 -@verbatim - 1| #!/bin/bash - 2| # - 3| # doSomthing.sh -- The function description goes here. - 4| # - 5| # Copyright (C) 2003, 2010 The CentOS Project - 6| # - 7| # This program is free software; you can redistribute it and/or modify - 8| # it under the terms of the GNU General Public License as published by - 9| # the Free Software Foundation; either version 2 of the License, or -10| # (at your option) any later version. -11| # -12| # This program is distributed in the hope that it will be useful, but -13| # WITHOUT ANY WARRANTY; without even the implied warranty of -14| # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -15| # General Public License for more details. -16| # -17| # You should have received a copy of the GNU General Public License -18| # along with this program; if not, write to the Free Software -19| # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 -20| # USA. -21| # -22| # ---------------------------------------------------------------------- -23| # $Id$ -24| # ---------------------------------------------------------------------- -25| -26| function doSomething { -27| -28| } -@end verbatim -@caption{The function script comment example} -@end float - -Relevant lines in the above structure are lines from 5 to 22. Pay -attention how the copyright line was built, and how the license was -added into the top comment where previously was just three dots. -Everything else in the file was left immutable. - -To change copyright information (i.e., full name or year information), -run the @code{shell} functionality over the root directory containing -the script files you want to update copyright in and enter the -appropriate information when it be requested. You can run the -@code{shell} functionality as many times as you need to. - -To change copyright license (i.e., the text in-between lines 7 and -20), you need to edit the @file{Config/tpl_forCopyright.sed} file, set -the appropriate information, and run the @code{shell} functionality -once again for changes to take effect over the files you specify. - -@quotation -@strong{Important} The @file{centos-art.sh} script is released as: - -@verbatim -GNU GENERAL PUBLIC LICENSE -Version 2, June 1991 - -Copyright (C) 1989, 1991 Free Software Foundation, Inc. -59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. -@end verbatim - -Do not change the license information under which @file{centos-art.sh} -script is released. Instead, if you think a different license must be -used, please share your reasons at @email{centos-devel@@centos-art.sh, -CentOS Developers mailing list}. -@end quotation - -@subsection Usage - -@table @command -@item centos-art sh --update-copyright='path/to/dir' -@itemx centos-art sh --update-copyright='path/to/dir' --filter='regex' -Use these commands to update copyright information in @samp{.sh} files -under @samp{path/to/dir} directory. -@end table - -When you provide @option{--filter='regex'} argument, the list of files -to process is reduced as specified in @samp{regex} regular expression. -Inside @file{centos-art.sh} script, the @samp{regex} regular -expression is used in combination with @command{find} command to look -for files matching the regular expression path pattern. - -@quotation -@strong{Warning} In order for @samp{regex} regular expression to match -a file, the @samp{regex} regular expresion must match the whole file -path not just the file name. -@end quotation - -For example, if you want to match all @file{render.conf.sh} files -inside @file{path/to/dir}, use the @code{.+/render.conf} regular -expression. Later, @file{centos-art.sh} script uses this value inside -@code{^$REGEX\.sh$} expression in order to build the final regular -expression (i.e., @code{^.+/render.conf\.sh$}) that is evaluated -against available file paths inside the list of files to process. - -Exceptionally, when you provide @option{--filter='regex'} in the way -that @samp{regex}, appended to @samp{path/to/dir/} (i.e. -@samp{path/to/dir/regex}), matches a regular file; the -@file{centos-art.sh} script uses the file matching as only file in the -list of files to process. - -@subsection See also - -@menu -* trunk Scripts Bash:: -@comment --- Removed(* trunk Scripts Bash Functions::) --- -@end menu diff --git a/Manuals/Filesystem/trunk/Scripts/Bash/centos-art/Functions/Svg.texi b/Manuals/Filesystem/trunk/Scripts/Bash/centos-art/Functions/Svg.texi deleted file mode 100644 index 341745d..0000000 --- a/Manuals/Filesystem/trunk/Scripts/Bash/centos-art/Functions/Svg.texi +++ /dev/null @@ -1,192 +0,0 @@ -@subsection Goals - -This section exists to organize files related to @code{svg} -functionality of @file{centos-art.sh} script. - -@subsection Description - -The @code{svg} functionality of @file{centos-art.sh} script helps you -to maintain scalable vector graphics (SVG) inside repository. For -example, suppose you've been working in CentOS default design models -under @file{trunk/Identity/Themes/Models/}, and you want to set common -metadata to all of them, and later remove all unused SVG defintions -from @samp{*.svg} files. Doing so file by file may be a tedious task, -so the @file{centos-art.sh} script provides the @code{svg} -functionality to aid you maintain such actions. - -@cindex Metadata maintainance -@subsubsection Metadata maintainance - -The metadata used is defined by Inkscape 0.46 using the SVG standard -markup. The @file{centos-art.sh} script replaces everything -in-between @code{} tags with a -predefined metadata template we've set for this purpose. - -The metadata template was created using the metadata information of a -file which, using Inkscape 0.46, all metadata fields were set. This -created a complete markup representation of how SVG metadata would -look like. Later, we replaced every single static value with a -translation marker in the form @samp{=SOMETEXT=}, where -@code{SOMETEXT} is the name of its main opening tag. Later, we -transform the metadata template into a sed replacement set of commads -escaping new lines at the end of each line. - -With metadata template in place, the @file{centos-art.sh} script uses -it to create a metadata template instance for the file being processed -currently. The metadata template instance contains the metadata -portion of sed replacement commands with translation markers already -traduced. In this action, instance creation, is where we take -advantage of automation and generate metadata values like title, date, -keywords, source, identifier, and relation dynamically, based on the -file path @file{centos-art.sh} script is currently creating metadata -information for. - -With metadata template instance in place, the @file{centos-art.sh} -script uses it to replace real values inside all @samp{.svg} files -under the current location you're running the @file{centos-art.sh} -script on. Default behaviour is to ask user to enter each metadatum -required, one by one. If user leaves metadatum empty, by pressing -@key{RET} key, @file{centos-art.sh} uses its default value. - -The @file{centos-art.sh} script modifies the following metadata: - -@table @samp -@item Title -Name by which this document is formally known. If no value is set -here, @file{centos-art.sh} script uses the file name as title. - -@item Date -Date associated with the creation of this document (YYYY-MM-DD). If no -value is set here, @file{centos-art.sh} script uses the current date -information as in @command{date +%Y-%m-%d}. - -@item Creator -Name of entity primarily responsible for making the content of this -document. If no value is set here, @file{centos-art.sh} script uses -the string @samp{The CentOS Project}. - -@item Rights -Name of entity with rights to the intellectual Property of this -document. If no value is set here, @file{centos-art.sh} script uses -the string @samp{The CentOS Project}. - -@item Publisher -Name of entity responsible for making this document available. If no -value is set here, @file{centos-art.sh} script uses the string -@samp{The CentOS Project}. - -@item Identifier -Unique URI to reference this document. If no value is set here, -@file{centos-art.sh} script uses the current file path to build the -related url that points to current file location inside repository -central server. - -@item Source -Unique URI to reference the source of this document. If no value is -set here, @file{centos-art.sh} script uses current file path to build -the related url that points to current file location inside repository -central server. - -@item Relation -Unique URI to a related document. If no value is set here, -@file{centos-art.sh} script uses current file path to build the -related url that points to current file location inside repository -central server. - -@item Language -Two-letter language tag with optional subtags for the language of this -document. (e.g. @samp{en-GB}). If no value is set here, -@file{centos-art.sh} script uses the current locale information as in -@code{cli_getCurrentLocale} function. - -@item Keywords -The topic of this document as comma-separated key words, prhases, or -classifications. If no value is set here, @file{centos-art.sh} script -uses file path to build - -@item Coverage -Extent or scope of this document. If no value is set here, -@file{centos-art.sh} script uses the string @samp{The CentOS Project}. - -@item Description -Description about the document. If no value is set here, -@file{centos-art.sh} script uses uses empty value as default. - -@item Contributors -People that contributes in the creation/maintainance of the document. -If no value is set here, @file{centos-art.sh} script uses uses empty -value as default. -@end table - -The @samp{License} metadatum is not set as a choise, by now. It is -fixed @url{http://creativecommons.org/licenses/by-sa/3.0/, Creative -Common Attribution Share-Alike 3.0 License}. This is done in order to -grant license consistency among all SVG files we manage inside CentOS -Artwork Repository. - -@cindex Unused definitions -@subsubsection Unused definitions - -Many of the no-longer-used gradients, patterns, and markers (more -precisely, those which you edited manually) remain in the -corresponding palettes and can be reused for new objects. However if -you want to optimize your document, use the @samp{Vacuum Defs} command -in @samp{File} menu. It will remove any gradients, patterns, or -markers which are not used by anything in the document, making the -file smaller. - -If you have one or two couple of files, removing unused definitions -using the graphical interface may be enough to you. In contrast, if -you have dozens or even houndreds of scalable vector graphics files to -maintain it is not a fun task to use the graphical interface to remove -unused definitions editing those files one by one. - -To remove unused definitions from several scalable vector graphics -files, the @file{centos-art.sh} script uses Inkscape command-line -interface, specifically with the @option{--vaccum-defs} option. - -@subsection Usage - -@table @command -@item centos-art svg --update-metadata='path/to/dir' -@item centos-art svg --update-metadata='path/to/dir' --filter='regex' -Use these commands to update metadata information to @samp{.svg} files -under @samp{path/to/dir} directory. - -@item centos-art svg --vacuum-defs='path/to/dir' -@item centos-art svg --vacuum-defs='path/to/dir' --filter='regex' -Use these commands to remove unused definitions inside @samp{.svg} -files under @samp{path/to/dir} directory. -@end table - -When you provide @option{--filter='regex'} argument, the list of files -to process is reduced as specified in @samp{regex} regular expression. -Inside @file{centos-art.sh} script, the @samp{regex} regular -expression is used in combination with @command{find} command to look -for files matching the regular expression path pattern. - -@quotation -@strong{Warning} In order for @samp{regex} regular expression to match -a file, the @samp{regex} regular expresion must match the whole file -path not just the file name. -@end quotation - -For example, if you want to match all @file{summary.svg} files inside -@file{path/to/dir}, use the @code{.+/summary} regular expression. -Later, @file{centos-art.sh} script uses this value inside -@code{^$REGEX\.svg$} expression in order to build the final regular -expression (i.e., @code{^.+/summary\.svg$}) that is evaluated against -available file paths inside the list of files to process. - -Exceptionally, when you provide @option{--filter='regex'} in the way -that @samp{regex}, appended to @samp{path/to/dir/} (i.e. -@samp{path/to/dir/regex}), matches a regular file; the -@file{centos-art.sh} script uses the file matching as only file in the -list of files to process. - -@subsection See also - -@menu -* trunk Scripts Bash:: -@comment --- Removed(* trunk Scripts Bash Functions::) --- -@end menu diff --git a/Manuals/Filesystem/trunk/Scripts/Bash/centos-art/Functions/Verify.texi b/Manuals/Filesystem/trunk/Scripts/Bash/centos-art/Functions/Verify.texi deleted file mode 100644 index ff98b51..0000000 --- a/Manuals/Filesystem/trunk/Scripts/Bash/centos-art/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 -* trunk Scripts Bash:: -@comment --- Removed(* trunk Scripts Bash Functions::) --- -@end menu diff --git a/Manuals/Filesystem/trunk/Scripts/Bash/cli.texi b/Manuals/Filesystem/trunk/Scripts/Bash/cli.texi new file mode 100755 index 0000000..e69de29 --- /dev/null +++ b/Manuals/Filesystem/trunk/Scripts/Bash/cli.texi diff --git a/Manuals/Filesystem/trunk/Scripts/Bash/cli/Functions.texi b/Manuals/Filesystem/trunk/Scripts/Bash/cli/Functions.texi new file mode 100755 index 0000000..2a421ab --- /dev/null +++ b/Manuals/Filesystem/trunk/Scripts/Bash/cli/Functions.texi @@ -0,0 +1,1222 @@ +@subsection Goals + +The @file{trunk/Scripts/Bash/Functions} directory exists to organize +@file{centos-art.sh} specific functionalities. + +@subsection Description + +The specific functions of @file{centos-art.sh} script are designed +with ``Software Toolbox'' philosophy (@pxref{Toolbox +introduction,,,coreutils.info}) in mind: each program ``should do one +thing well''. Inside @file{centos-art.sh} script, each specific +functionality is considered a program that should do one thing well. +Of course, if you find that they still don't do it, feel free to +improve them in order for them to do so. + +The specific functions of @file{centos-art.sh} script are organized +inside specific directories under @file{trunk/Scripts/Bash/Functions} +location. Each specific function directory should be named as the +function it represents, with the first letter in uppercase. For +example, if the function name is @code{render}, the specific function +directory for it would be @samp{trunk/Scripts/Bash/Functions/Render}. + +To better understand how specific functions of @file{centos-art.sh} +script are designed, lets create one function which only goal is to +output different kind of greetings to your screen. + +When we create specific functions for @file{centos-art.sh} script it +is crucial to know what these functions will do exactly and if there +is any function that already does what we intend to do. If there is no +one, it is good time to create them then. Otherwise, if +functionalities already available don't do what you exactly expect, +contact their authors and work together to improve them. + +@quotation +@strong{Tip} Join CentOS developers mailing list +@email{centos-art@@centos.org} to share your ideas. +@end quotation + +It is also worth to know what global functions and variables do we +have available inside @file{centos-art.sh} script, so advantage can be +taken from them. Global variables are defined inside global function +scripts. Global functions scripts are stored immediatly under +@file{trunk/Scripts/Bash/Functions} directory, in files begining with +@samp{cli} prefix. + +OK, let's begin with our functionality example. + +What function name do we use? Well, lets use @code{greet}. Note that +@samp{hello} word is not a verb; but an expression, a kind of +greeting, an interjection specifically. In contrast, @samp{greet} is a +verb and describes what we do when we say @samp{Hello!}, @samp{Hi!}, +and similar expressions. + +So far, we've gathered the following function information: + +@verbatim +Name: greet +Path: trunk/Scripts/Bash/Functions/Greet +File: trunk/Scripts/Bash/Functions/Greet/greet.sh +@end verbatim + +The @file{greet.sh} function script is the first file +@file{centos-art.sh} script loads when the @samp{greet} functionality +is called using commands like @samp{centos-art greet --hello='World'}. +The @file{greet.sh} function script contains the @code{greet} function +definition. + +Inside @file{centos-art.sh} script, as convenction, each function +script has one top commentary, followed by one blank line, and then +one function defintion below it only. + +Inside @file{centos-art.sh} script functions, top commentaries have +the following components: the functionality description, one-line for +copyright note with your personal information, the license under +which the function source code is released ---the @file{centos-art.sh} +script is released as GPL, so do all its functions---, the @code{$Id$} +keyword of Subversion is later expanded by @command{svn propset} +command. + +In our @code{greet} function example, top commentary for +@file{greet.sh} function script would look like the following: + +@verbatim +#!/bin/bash +# +# greet.sh -- This function outputs different kind of greetings to +# your screen. Use this function to understand how centos-art.sh +# script specific functionalities work. +# +# Copyright (C) YEAR YOURFULLNAME +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, but +# WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +# General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 +# USA. +# +# ---------------------------------------------------------------------- +# $Id$ +# ---------------------------------------------------------------------- +@end verbatim + +After top commentary, separated by one blank line, the @code{greet} +function definition would look like the following: + +@verbatim +function greet { + + # Define global variables. + + # Define command-line interface. + greet_getActions + +} +@end verbatim + +The first definition inside @code{greet} function, are global +variables that will be available along @code{greet} function execution +environment. This time we didn't use global variable definitions for +@code{greet} function execution environment, so we left that section +empty. + +Later, we call @code{greet_getActions} function to define the +command-line interface of @code{greet} functionality. The command-line +interface of @code{greet} functionality defines what and how actions +are performed, based on arguments combination passed to +@file{centos-art.sh} script. + +@verbatim +function greet_getActions { + + case "$ACTIONNAM" in + + --hello ) + greet_doHello + ;; + + --bye ) + greet_doBye + ;; + + * ) + cli_printMessage "`gettext "The option provided is not valid."`" + cli_printMessage "$(caller)" 'AsToKnowMoreLine' + + esac + +} +@end verbatim + +The @var{ACTIONNAM} global variable is defined in @file{cli.sh} +function script and contains the value passed before the equal sign +(i.e., @samp{=}) in the second command-line argument of +@file{centos-art.sh} script. For example, if the second command-line +argument is @option{--hello='World'}, the value of @var{ACTIONNAM} +variable would be @samp{--hello}. Using this configuration let us +deside which action to perform based on the action name passed to +@file{centos-art.sh} script as second argument. + +The @code{greet} function definition makes available two valid +greetings through @option{--hello} and @option{--bye} options. If no +one of them is provided as second command-line argument, the @samp{*} +case is evaluated instead. + +The @samp{*} case and its two lines further on should always be +present in @file{_getActions.sh} function scripts, no matter what +specific functionality you are creating. This convenction helps the +user to find out documentation about current functionality in use, +when no valid action is provided. + +The @code{greet_doHello} and @code{greet_doBye} function definitions +are the core of @code{greet} specific functionality. In such function +definitions we set what our @code{greet} function really does: to +output different kinds of greetings. + +@verbatim +function greet_doHello { + + cli_printMessage "`gettext "Hello"` $ACTIONVAL" + +} +@end verbatim + +The @code{greet_doHello} function definition is stored in +@file{greet_doHello.sh} function script. + +@verbatim +function greet_doBye { + + cli_printMessage "`gettext "Goodbye"` $ACTIONVAL" + +} +@end verbatim + +The @code{greet_doBye} function definition is stored in the +@file{greet_doBye.sh} function script. + +Both @file{greet_doHello.sh} and @file{greet_doBye.sh} function +scripts are stored inside @code{greet} function directory path (i.e. +@file{trunk/Scripts/Bash/Functions/Greet}). + +The @var{ACTIONVAL} global variable is defined in @file{cli.sh} +function script and contains the value passed after the equal sign +(i.e., @samp{=}) in the second command-line argument of +@file{centos-art.sh} script. For example, if the second command-line +argument is @option{--hello='World'}, the value of @var{ACTIONVAL} +variable would be @samp{World} without quotes. + +Let's see how @code{greet} specific functionality files are organzied +under @code{greet} function directory. To see file organization we use +the @command{tree} command: + +@verbatim +trunk/Scripts/Bash/Functions/Greet +|-- greet_doBye.sh +|-- greet_doHello.sh +|-- greet_getActions.sh +`-- greet.sh +@end verbatim + +To try the @code{greet} specific functionality we've just created, +pass the function name (i.e., @samp{greet}) as first argument to +@file{centos-art.sh} script, and any of the valid options as second +argument. Some examples are illustrated below: + +@verbatim +[centos@projects ~]$ centos-art greet --hello='World' +Hello World +[centos@projects ~]$ centos-art greet --bye='World' +Goodbye World +[centos@projects ~]$ +@end verbatim + +The word @samp{World} in the examples above can be anything. In fact, +change it to have a little fun. + +Now that we have a specific function that works as we expect, it is +time to document it. To document @code{greet} specific functionality, +we use its directory path and the @code{manual} functionality +(--- @strong{Removed}(pxref:trunk Scripts Bash Functions Manual) ---) of @file{centos-art.sh} +script, just as the following command illustrates: + +@verbatim +centos-art manual --edit=trunk/Scripts/Bash/Functions/Greet +@end verbatim + +To have a well documented function helps user to understand how your +function really works, and how it should be used. When no valid +action is passed to a function, the @file{centos-art.sh} script uses +the function documentation entry as vehicle to communicate which the +valid functions are. When no documentation entry exists for a +function, the @file{centos-art.sh} script informs that no +documentation entry exists for such function and requests user to +create it right at that time. + +Now that we have documented our function, it is time to translate its +output messages to different languages. To translate specific +functionality output messages to different languages we use the +@code{locale} functionality (--- @strong{Removed}(pxref:trunk Scripts Bash Functions +Locale) ---) of @file{centos-art.sh} script, just as the following command +illustrates: + +@verbatim +centos-art locale --edit +@end verbatim + +@quotation +@strong{Warning} To translate output messages in different languages, +your system locale information ---as in @env{LANG} environment +variable--- must be set to that locale you want to produce translated +messages for. For example, if you want to produce translated messages +for Spanish language, your system locale information must be set to +@samp{es_ES.UTF-8}, or similar, first. +@end quotation + +Well, it seems that our example is rather complete by now. + +In @code{greet} function example we've described so far, we only use +@command{cli_printMessage} global function in action specific function +definitions in order to print messages, but more interesting things +can be achieved inside action specific function definitions. For +example, if you pass a directory path as action value in second +argument, you could retrive a list of files from therein, and process +them. If the list of files turns too long or you just want to control +which files to process, you could add the third argument in the form +@option{--filter='regex'} and reduce the amount of files to process +using a regular expression pattern. + +The @code{greet} function described in this section may serve you as +an introduction to understand how specific functionalities work inside +@file{centos-art.sh} script. With some of luck this introduction will +also serve you as motivation to create your own @file{centos-art.sh} +script specific functionalities. + +By the way, the @code{greet} functionality doesn't exist inside +@file{centos-art.sh} script yet. Would you like to create it? + +@subsection Usage + +@subsubsection Global variables + +The following global variables of @file{centos-art.sh} script, are +available for you to use inside specific functions: + +@defvar TEXTDOMAIN +Default domain used to retrieve translated messages. This value is set +in @file{initFunctions.sh} and shouldn't be changed. +@end defvar + +@defvar TEXTDOMAINDIR +Default directory used to retrieve translated messages. This value is +set in @file{initFunctions.sh} and shouldn't be changed. +@end defvar + +@defvar FUNCNAM +Define function name. + +Function names associate sets of actions. There is one set of actions +for each unique function name inside @file{centos-art.sh} script. + +Dunction names are passed as first argument in @file{centos-art.sh} +command-line interface. For example, in the command @samp{centos-art +render --entry=path/to/dir --filter=regex}, the @var{ACTION} passed to +@file{centos-art.sh} script is @option{render}. + +When first argument is not provided, the @file{centos-art.sh} script +immediatly ends its execution. +@end defvar + +@defvar FUNCDIR +@end defvar + +@defvar FUNCDIRNAME +@end defvar + +@defvar FUNCSCRIPT +@end defvar + +@defvar FUNCCONFIG +@end defvar + +@defvar ACTIONNAM +Define action name. + +Each action name identifies an specific action to perform, inside an +specific function. + +Action name names aare passed as second argument in +@file{centos-art.sh} command-line interface. For example, in the +command @samp{centos-art render --entry=path/to/dir --filter=regex}, +the @var{ACTIONNAM} passed to @file{centos-art.sh} script is +@option{--entry}. + +When second argument is not provided, the @file{centos-art.sh} script +immediatly ends its execution. +@end defvar + +@defvar ACTIONVAL +Define action value. + +Action values are associated to just one action name. Action values +contain the working copy entry over which its associated action will be +performed in. Working copy entries can be files or directories inside +the working copy. +@end defvar + +@defvar REGEX +Define regular expression used as pattern to build the list of files +to process. + +By default, @var{REGEX} variable is set to @code{.+} to match all +files. + +Functions that need to build a list of files to process use the option +@option{--filter} to redefine @var{REGEX} variable default value, and +so, control the amount of files to process. +@end defvar + +@defvar ARGUMENTS +Define optional arguments. + +Optional arguments, inside @file{centos-art.sh} script, are considered +as all command-line arguments passed to @file{centos-art.sh} script, +from third argument position on. For example, in the command +@samp{centos-art render --entry=path/to/dir --filter=regex} , the +optional arguments are from @samp{--filter=regex} argument on. + +Optional arguments are parsed using @command{getopt} command through +the following base construction: + +@verbatim +# Define short options we want to support. +local ARGSS="" + +# Define long options we want to support. +local ARGSL="filter:,to:" + +# Parse arguments using getopt(1) command parser. +cli_doParseArguments + +# Reset positional parameters using output from (getopt) argument +# parser. +eval set -- "$ARGUMENTS" + +# Define action to take for each option passed. +while true; do + case "$1" in + --filter ) + REGEX="$2" + shift 2 + ;; + --to ) + TARGET="$2" + shift 2 + ;; + * ) + break + esac +done +@end verbatim + +Optional arguments provide support to command options inside +@file{centos-art.sh} script. For instance, consider the Subversion +(@command{svn}) command, where there are many options (e.g., +@option{copy}, @option{delete}, @option{move}, etc), and inside each +option there are several modifiers (e.g., @samp{--revision}, +@samp{--message}, @samp{--username}, etc.) that can be combined one +another in their short or long variants. + +The @var{ARGUMENTS} variable is used to store arguments passed from +command-line for later use inside @file{centos-art.sh} script. Storing +arguments is specially useful when we want to run a command with some +specific options from them. Consider the following command: + +@verbatim +centos-art path --copy=SOURCE --to=TARGET --message="The commit message goes here." --username='johndoe' +@end verbatim + +In the above command, the @option{--message}, and @option{--username} +options are specific to @command{svn copy} command. In such cases, +options are not interpreted by @file{centos-art.sh} script itself. +Instead, the @file{centos-art.sh} script uses @command{getopt} to +retrive them and store them in the @var{ARGUMENTS} variable for later +use, as described in the following command: + +@verbatim +# Build subversion command to duplicate locations inside the +# workstation. +eval svn copy $SOURCE $TARGET --quiet $ARGUMENTS +@end verbatim + +When @command{getopt} parses @var{ARGUMENTS}, we may use short options +(e.g., @option{-m}) or long options (e.g., @option{--message}). When +we use short options, arguments are separated by one space from the +option (e.g., @option{-m 'This is a commit message.'}). When we use +long options arguments are separated by an equal sign (@samp{=}) +(e.g., @option{--message='This is a commit message'}). + +In order for @command{getopt} to parse @var{ARGUMENTS} correctly, it +is required to provide the short and long definition of options that +will be passed or at least supported by the command performing the +final action the function script exists for. + +As convenction, inside @file{centos-art.sh} script, short option +definitions are set in the @var{ARGSS} variable; and long option +definitions are set in the @var{ARGSL} variable. + +When you define short and long options, it may be needed to define +which of these option arguments are required and which not. To define +an option argument as required, you need to set one colon @samp{:} +after the option definition (e.g., @option{-o m: -l message:}). On +the other hand, to define an option argument as not required, you need +to set two colons @samp{::} after the option definition (e.g., +@option{-o m:: -l message::}). +@end defvar + +@defvar 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. +@end defvar + +@subsubsection Global functions + +Function scripts stored directly under +@file{trunk/Scripts/Bash/Functions/} directory are used to define +global functions. Global functions can be used inside action specific +functionalities and or even be reused inside themselves. This section +provides introductory information to global functions you can use +inside @file{centos-art.sh} script. + +@defun cli_checkActionArguments +Validate action value (@var{ACTIONVAL}) variable. + +The action value variable can take one of the following values: + +@enumerate +@item Path to one directory inside the local working copy, +@item Path to one file inside the local working copy, +@end enumerate + +If another value different from that specified above is passed to +action value variable, the @file{centos-art.sh} script prints an error +message and ends script execution. +@end defun + +@defun cli_checkFiles FILE [TYPE] +Verify file existence. + +@code{cli_checkFiles} receives a @var{FILE} absolute path and performs +file verification as specified in @var{TYPE}. When @var{TYPE} is not +specified, @code{cli_checkFiles} verifies @var{FILE} existence, no +matter what kind of file it be. If @var{TYPE} is specified, use one +of the following values: + +@table @option +@item d +@itemx directory +Ends script execution if @var{FILE} is not a directory. + +When you verify directories with cli_checkFiles, if directory doesn't +exist, @file{centos-art.sh} script asks you for confirmation in order +to create that directory. If you answer positively, +@file{centos-art.sh} script creates that directory and continues +script flows normally. Otherwise, if you answer negatively, +@file{centos-art.sh} ends script execution with an error and +documentation message. + +@item f +@item regular-file +Ends script execution if @var{FILE} is not a regular file. +@item h +@itemx symbolic-link +Ends script execution if @var{FILE} is not a symbolic link. +@item x +@itemx execution +Ends script execution if @var{FILE} is not executable. +@item fh +Ends script execution if @var{FILE} is neither a regular file nor a +symbolic link. +@item fd +Ends script execution if @var{FILE} is neither a regular file nor a +directory. +@item isInWorkingCopy +Ends script execution if @var{FILE} is not inside the working copy. +@end table + +As default behaviour, if @var{FILE} passes all verifications, +@file{centos-art.sh} script continues with its normal flow. +@end defun + +@defun cli_commitRepoChanges [LOCATION] + +Syncronize changes between repository and working copy. + +The @code{cli_commitRepoChanges} function brings changes from the +central repository down to the working copy---using @command{svn +update}---, checks the working copy changes---using @command{svn +status} command---, prints status report---using both @command{svn +update} and @command{svn status} commands output, and finally, commits +recent changes from the working copy up to the repository---using +@command{svn commit} command---. + +Previous to commit the working copy changes up to the central +repository, the @code{cli_commitRepoChanges} function asks you to +verify changes---using @command{svn diff} command---, and later, +another confirmation question is shown to be sure you really want to +commit changes up to central repository. + +If @var{LOCATION} argument is not specified, the value of +@var{ACTIONVAL} variable is used as reference instead. + +@float Figure, trunk/Scripts/Bash/Functions/cli_commitRepoChanges +@verbatim +---------------------------------------------------------------------- +--> Bringing changes from the repository into the working copy +--> Checking changes in the working copy +---------------------------------------------------------------------- +Added 0 file from the repository. +Deleted 0 file from the repository. +Updated 0 file from the repository. +Conflicted 0 file from the repository. +Merged 0 file from the repository. +Modified 4 files from the working copy. +Unversioned 0 file from the working copy. +Deleted 0 file from the working copy. +Added 0 file from the working copy. +---------------------------------------------------------------------- +@end verbatim +@caption{The @code{cli_commitRepoChanges} function output.} +@end float + +Call the @code{cli_commitRepoChanges} function before or/and after +calling functions that modify files or directories inside the working +copy as you may need to. +@end defun + +@defun cli_doParseArguments +Redefine arguments (@var{ARGUMENTS}) global variable using +@command{getopt} command output. For more information about how to use +@code{cli_doParseArguments} function, see @var{ARGUMENTS} variable +description above. +@end defun + +@defun cli_doParseArgumentsReDef $@@ +Initialize/reset arguments (@var{ARGUMENTS}) global variable using +positional parameters variable (@var{$@@}) as reference. + +When we work inside function definitions, positional parameters are +reset to the last function definition positional parameters. If you +need to redefine positional parameters from one specific function, you +need to call @code{cli_doParseArgumentsReDef} with the positional +parameters variable (@var{$@@}), set as first argument, to that +specific function you want to redefine positional parameters at. +@end defun + +@defun cli_getArguments + +Initialize function name (@var{FUNCNAM}), action name +(@var{ACTIONNAM}), and action value (@var{ACTIONVAL}) global +variables, using positional parameters passed in @var{$@@} variable. + +The @code{cli_getArguments} function is called from @code{cli.sh} +function script, using @code{cli} function positional parameters +(i.e., the positional parameters passed as arguments in the +command-line) as first function argument. + +Once command-line positional parameters are accesible to +@file{centos-art.sh} script execution evironment, +@code{cli_getArguments} uses regular expression to retrive +action variables from first and second argument. The first argument +defines the value used as function name (@var{FUNCNAM}), and the +second argument defines both values used as action name +(@var{ACTIONNAM}) and action value (@var{ACTIONVAL}), respectively. + +The first argument is a word in lower case. This word specifies the +name of the functionality you want to use (e.g., @samp{render} to +render images, @samp{manual} to work on documentation, and so on.) + +The second argument has a long option style (e.g., +@samp{--option=value}). The @samp{--option} represents the action name +(@var{ACTIONNAM}), and the characters inbetween the equal sign +(@samp{=}) and the first space character, are considered as the action +value (@var{ACTIONVAL}). In order to provide action values with space +characters inbetween you need to enclose action value with quotes like +in @samp{--option='This is long value with spaces inbetween'}. +Generally, action values are used to specify paths over which the +action name acts on. + +Once action related variables (i.e., @var{FUNCNAM}, @var{ACTIONNAM}, +and @var{ACTIONVAL}) are defined and validated, +@code{cli_getArguments} shifts the positional arguments to remove the +first two arguments passed (i.e., those used to retrive action related +variables) and redefine the arguments (@var{ARGUMENTS}) global +variable with the new positional parameters information. +@end defun + +@defun cli_getFunctions +Initialize funtionalities supported by @file{centos-art.sh} script. + +Functionalities supported by @file{centos-art.sh} script are organized +in functionality directories under +@file{trunk/Scripts/Bash/Functions/} directory. Each functionality +directory stores function scripts to the functionality such directory +was created for. Function scripts contain function definitions. +Function definitions contain several commands focused on achieving one +specific task only (i.e., the one such functionality was created for). + +In order for @file{centos-art.sh} script to recognize a functionality, +such functionality needs to be stored under +@file{trunk/Scripts/Bash/Functions/} in a directory written +capitalized (i.e., the whole name is written in lowercase except the +first character which is in uppercase). The directory where one +specific functionality is stored is known as the @samp{functionality +directory}. + +Inside each functionality directory, the functionalty itself is +implemented through function scripts. Function scripts are organized +in files independently one another and written in @samp{camelCase} +format with the function name as prefix. Separation between prefix +and description is done using underscore (@samp{_}) character. + +In order for @file{centos-art.sh} script to load functionalities +correctly, function definition inside function scripts should be set +using the @samp{function} reserved word, just as in the following +example: + +@verbatim +function prefix_doSomething { + + # Do something here... + +} +@end verbatim + +The above function definition is just a convenction we use, in order +to make identification of function names easier read and automate by +@file{centos-art.sh} script initialization commands, once +@file{centos-art.sh} script determines which functionality directory +to use. Specifically, in order to initialize and export functions, +@file{centos-art.sh} script executes all function scripts inside the +functionality directory, and later @command{grep} on them using a +regular expression pattern, where the @samp{function} reserved word is +used as reference to retrive the function names and export them to +@file{centos-art.sh} script execution environment, and so, make +function definitions ---from function scripts inside the functionality +directory--- available for further calls. + +If the functionality specified in the command-line first argument +doesn't have a functionality directory, @file{centos-art.sh} script +considers the functionality provided in the command-line as invalid +functionality and immediatly stops script execution with an error +message. + +In order to keep visual consistency among function scripts, please +consider using the following function script design model as template +for your own function scripts: + +@verbatim +#!/bin/bash +# +# prefix_doSomething.sh -- This function illustrates function scripts +# design model you can use to create your own function scripts inside +# centos-art.sh script. +# +# Copyright (C) YEAR YOURFULLNAME +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, but +# WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +# General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 +# USA. +# +# ---------------------------------------------------------------------- +# $Id$ +# ---------------------------------------------------------------------- + +function prefix_doSomething { + + # Do something here... + +} +@end verbatim +@end defun + +@defun cli_getCountryCodes [FILTER] +Output country codes supported by @file{centos-art.sh} script. + +The @code{cli_getCountryCodes} function outputs a list with country +codes as defined in ISO3166 standard. When @var{FILTER} is provided, +@code{cli_getCountryCodes} outputs country codes that match +@var{FILTER} regular expression pattern. +@end defun + +@defun cli_getCountryName [FILTER] +Outputs country name supported by @file{centos-art.sh} script. + +The @code{cli_getCountryName} function reads one language locale code +in the format LL_CC and outputs the name of its related country as in +ISO3166. If filter is specified, @code{cli_getCountryName} returns the +country name that matches the locale code specified in @var{FILTER}, +exactly. +@end defun + +@defun cli_getCurrentLocale +Output current locale used by @file{centos-art.sh} script. + +The @code{cli_getCurrentLocale} function uses @env{LANG} environment +variable to build a locale pattern that is later applied to +@code{cli_getLocales} function output in order to return the current +locale that @file{centos-art.sh} script works with. + +The current locale information, returned by +@code{cli_getCurrentLocale}, is output from more specific to less +specific. For example, if @samp{en_GB} locale exists in +@code{cli_getLocales} function output, the @samp{en_GB} locale would +take precedence before @samp{en} locale. + +Locale precedence selection is quite important in order to define the +locale type we use for message translations. For example, if +@samp{en_GB} is used, we are also saying that the common language +specification for English language (i.e., @samp{en}) is no longer +used. Instead, we are using English non-common country-specific +language specifications like @samp{en_AU}, @samp{en_BW}, @samp{en_GB}, +@samp{en_US}, etc., for message translations. + +Use @code{cli_getCurrentLocale} function to know what current locale +information to use inside @file{centos-art.sh} script. +@end defun + +@defun cli_getFilesList [LOCATION] +Output list of files to process. + +The @code{cli_getFilesList} function uses @var{LOCATION} variable as +source location to build a list of files just as specified by regular +expression (@var{REGEX}) global variable. Essentially, what the +@code{cli_getFilesList} function does is using @command{find} command +to look for files in the location (@var{LOCATION}) just as posix-egrep +regular expression (@var{REGEX}) specifies. + +If @var{LOCATION} is not specified when @code{cli_getFilesList} +function is called, the action value (@var{ACTIONVAL}) global variable +is used as location value instead. + +By default, if the regular expression (@var{REGEX}) global variable is +not redefined after its first definition in the @code{cli} function, +all files that match default regular expression value (i.e., +@samp{.+}) will be added to the list of files to process. Otherwise, +if you redefine the regular expression global variable after its first +definition in the @code{cli} function and before calling +@code{cli_getFilesList} function, the last value you specifed is used +instead. + +When you need to customize the regular expression (@var{REGEX}) global +variable value inside a function, do not redefine the global variable +(at least you be absolutly convinced you need to). Instead, set the +regular expression global variable as @samp{local} to the function you +need a customized regular expression value for. If we don't redefine +the regular expression global variable as local to the function, or +use another name for the regular expression variable (which is not +very convenient in order to keep the amount of names to remember low), +you may experiment undesired concantenation issues that make your +regular expression to be something different from that you expect them +to be, specially if the function where you are doing the variable +redefinition is called several times during the same script execution. + +As result, the @code{cli_getFilesList} re-defines the value of +@var{FILES} variable with the list of files the @command{find} command +returned. As example, consider the following construction: + +@verbatim +function prefix_doSomething { + + # Initialize the list of files to process. + local FILES='' + + # Initialize location. + local LOCATION=/home/centos/artwork/trunk/Identity/Themes/Models/Default + + # Re-define regular expression to match scalable vector graphic + # files only. Note how we use the global value of REGEX to build a + # new local REGEX value here. + local REGEX="${REGEX}.*\.(svgz|svg)" + + # Redefine list of files to process. + cli_getFilesList $LOCATION + + # Process list of files. + for FILE in $FILES;do + cli_printMessages "$FILE" 'AsResponseLine' + # Do something else here on... + done + +} +@end verbatim + +@end defun + +@defun cli_getLangCodes [FILTER] +Outputs language codes supported by @file{centos-art.sh} script. + +@code{cli_getLangCodes} function outputs a list of language codes as +defined in ISO639 standard. When @var{FILTER} is provided, +@code{cli_getLangCodes} outputs language codes that match @var{FILTER} +regular expression pattern. +@end defun + +@defun cli_getLangName [FILTER] +Outputs language names supported by @file{centos-art.sh} script. + +@code{cli_getLangName} function reads one language locale code in the +format LL_CC and outputs the language related name as in ISO639. If +filter is specified, @code{cli_getLangName} returns the language name +that matches the locale code specified in @var{FILTER}, exactly. +@end defun + +@defun cli_getLocales +Output locale codes supported by @file{centos-art.sh} script. + +Occasionally, you use @code{cli_getLocales} function to add locale +information in non-common country-specific language (@samp{LL_CC}) +format for those languages (e.g., @samp{bn_IN}, @samp{pt_BR}, etc.) +which locale differences cannot be solved using common language +specifications (@samp{LL}) into one unique common locale specification +(e.g., @samp{bn}, @samp{pt}, etc.). +@end defun + +@defun cli_getRepoName NAME TYPE +Sanitate file names. + +Inside @file{centos-art.sh} script, specific functionalities rely both +in @code{cli_getRepoName} and repository file system organization to +achieve their goals. Consider @code{cli_getRepoName} function as +central place to manage file name convenctions for other functions +inside @file{centos-art.sh} script. + +@quotation +@strong{Important} @code{cli_getRepoName} function doesn't verify file +or directory existence, for that purpose use @code{cli_checkFiles} +function instead. +@end quotation + +The @var{NAME} variable contains the file name or directory name you +want to sanitate. + +The @var{TYPE} variable specifies what type of sanitation you want to +perform on @var{NAME}. The @var{TYPE} can be one of the following +values: + +@table @option +@item d +@itemx directory +Sanitate directory @var{NAME}s. +@item f +@item regular-file +Sanitate regular file @var{NAME}s. +@end table + +Use @code{cli_getRepoName} function to sanitate file names and +directory names before their utilization. + +Use @code{cli_getRepoName} when you need to change file name +convenctions inside @file{centos-art.sh} script. + +When we change file name convenctions inside @code{cli_getRepoName} +what we are really changing is the way functions interpret repository +file system organization. Notice that when we change a file name +(e.g., a function name), it is necessary to update all files where +such file name is placed on. This may require a massive substitution +inside the repository, each time we change name convenctions in the +repository (--- @strong{Removed}(pxref:trunk Scripts Bash Functions Path) ---, for more +information). +@end defun + +@defun cli_getRepoStatus [LOCATION] +Request repository status. + +This function requests the status of a @var{LOCATION} inside the +working copy using the @command{svn status} command and returns the +first character in the output line, just as described in @command{svn +help status}. If @var{LOCATION} is not a regular file or a directory, +inside the working copy, the @file{centos-art.sh} script prints a +message and ends its execution. + +Use this function to perform verifications based a repository +@var{LOCATION} status. +@end defun + +@defun cli_getTemporalFile @var{NAME} +Output absolute path to temporal file @var{NAME}. + +The @code{cli_getTemporalFile} function uses @file{/tmp} directory as +source location to store temporal files, the @file{centos-art.sh} +script name, and a random identification string to let you run more +than one @file{centos-art.sh} script simultaneously on the same user +session. For example, due the following temporal file defintion: + +@verbatim +cli_getTemporalFile $FILE +@end verbatim + +If @var{FILE} name is @file{instance.svg} and the unique random string +is @samp{f16f7b51-ac12-4b7f-9e66-72df847f12de}, the final temporal +file, built from previous temporal file definition, would be: + +@verbatim +/tmp/centos-art.sh-f16f7b51-ac12-4b7f-9e66-72df847f12de-instance.svg +@end verbatim + +When you use the @code{cli_getTemporalFile} function to create +temporal files, be sure to remove temporal files created once you've +ended up with them. For example, consider the following construction: + +@verbatim +for FILE in $FILES;do + + # Initialize temporal instance of file. + INSTANCE=$(cli_getTemporalFile $FILE) + + # Do something ... + + # Remove temporal instance of file. + if [[ -f $INSTANCE ]];then + rm $INSTANCE + fi + +done +@end verbatim + +Use the @code{cli_getTemporalFile} function whenever you need to +create temporal files inside @file{centos-art.sh} script. +@end defun + +@defun cli_getThemeName +Output theme name. + +In order for @code{cli_getThemeName} function to extract theme name +correctly, the @var{ACTIONVAL} variable must contain a directory path +under @file{trunk/Identity/Themes/Motifs/} directory structure. +Otherwise, @code{cli_getThemeName} returns an empty string. +@end defun + +@defun cli_printMessage MESSAGE [FORMAT] +Define standard output message definition supported by +@file{centos-art.sh} script. + +When @var{FORMAT} is not specified, @code{cli_printMessage} outputs +information just as it was passed in @var{MESSAGE} variable. +Otherwise, @var{FORMAT} can take one of the following values: + +@table @option +@item AsHeadingLine +To print heading messages. +@verbatim +---------------------------------------------------------------------- +$MESSAGE +---------------------------------------------------------------------- +@end verbatim + +@item AsWarningLine +To print warning messages. +@verbatim +---------------------------------------------------------------------- +WARNING: $MESSAGE +---------------------------------------------------------------------- +@end verbatim + +@item AsNoteLine +To print note messages. +@verbatim +---------------------------------------------------------------------- +NOTE: $MESSAGE +---------------------------------------------------------------------- +@end verbatim + +@item AsUpdatingLine +To print @samp{Updating} messages on two-columns format. +@verbatim +Updating $MESSAGE +@end verbatim + +@item AsRemovingLine +To print @samp{Removing} messages on two-columns format. +@verbatim +Removing $MESSAGE +@end verbatim + +@item AsCheckingLine +To print @samp{Checking} messages on two-columns format. +@verbatim +Checking $MESSAGE +@end verbatim + +@item AsCreatingLine +To print @samp{Creating} messages on two-columns format. +@verbatim +Creating $MESSAGE +@end verbatim + +@item AsSavedAsLine +To print @samp{Saved as} messages on two-columns format. +@verbatim +Saved as $MESSAGE +@end verbatim + +@item AsLinkToLine +To print @samp{Linked to} messages on two-columns format. +@verbatim +Linked to $MESSAGE +@end verbatim + +@item AsMovedToLine +To print @samp{Moved to} messages on two-columns format. +@verbatim +Moved to $MESSAGE +@end verbatim + +@item AsTranslationLine +To print @samp{Translation} messages on two-columns format. +@verbatim +Translation $MESSAGE +@end verbatim + +@item AsConfigurationLine +To print @samp{Configuration} messages on two-columns format. +@verbatim +Configuration $MESSAGE +@end verbatim + +@item AsResponseLine +To print response messages on one-column format. +@verbatim +--> $MESSAGE +@end verbatim + +@item AsRequestLine +To print request messages on one-column format. Request messages +output messages with one colon (@samp{:}) and without trailing newline +(@samp{\n}) at message end. +@verbatim +$MESSAGE: +@end verbatim + +@item AsYesOrNoRequestLine +To print @samp{yes or no} request messages on one-column format. If +something different from @samp{y} is answered (when using +@code{en_US.UTF-8} locale), script execution ends immediatly. + +@verbatim +$MESSAGE [y/N]: +@end verbatim + +When we use @file{centos-art.sh} script in a locale different from +@code{en_US.UTF-8}, confirmation answer may be different from +@samp{y}. For example, if you use @code{es_ES.UTF-8} locale, the +confirmation question would look like: + +@verbatim +$MESSAGE [s/N]: +@end verbatim + +and the confirmation answer would be @samp{s}, as it is on Spanish +@samp{sí} word. + +Definition of which confirmation word to use is set on translation +messages for your specific locale information. --- @strong{Removed}(xref:trunk Scripts +Bash Functions Locale) ---, for more information about locale-specific +translation messages. + +@item AsToKnowMoreLine +To standardize @samp{to know more, run the following command:} +messages. When the @option{AsToKnowMoreLine} option is used, the +@var{MESSAGE} value should be set to @code{"$(caller)"}. @code{caller} +is a Bash builtin that returns the context of the current subroutine +call. @option{AsToKnowMoreLine} option uses @code{caller} builtin +output to build documentation entries dynamically. + +@verbatim +---------------------------------------------------------------------- +To know more, run the following command: +centos-art manual --read='path/to/dir' +---------------------------------------------------------------------- +@end verbatim + +Use @option{AsToKnowMoreLine} option after errors and for intentional +script termination. + +@item AsRegularLine +To standardize regular messages on one-column format. + +When @var{MESSAGE} contains a colon inside (e.g., @samp{description: +message}), the @code{cli_printMessage} function outputs @var{MESSAGE} +on two-columns format. +@end table + +Use @code{cli_printMessage} function whenever you need to output +information from @file{centos-art.sh} script. + +@quotation +@strong{Tip} To improve two-columns format, change the following file: +@verbatim +trunk/Scripts/Bash/Styles/output_forTwoColumns.awk +@end verbatim +@end quotation +@end defun + +@subsubsection Specific functions + +The following specific functions of @file{centos-art.sh} script, are +available for you to use: + +@menu +@comment --- Removed(* trunk Scripts Bash Functions Html::) --- +@comment --- Removed(* trunk Scripts Bash Functions Locale::) --- +@comment --- Removed(* trunk Scripts Bash Functions Manual::) --- +@comment --- Removed(* trunk Scripts Bash Functions Path::) --- +@comment --- Removed(* trunk Scripts Bash Functions Render::) --- +@comment --- Removed(* trunk Scripts Bash Functions Render Config::) --- +@comment --- Removed(* trunk Scripts Bash Functions Shell::) --- +@comment --- Removed(* trunk Scripts Bash Functions Svg::) --- +@comment --- Removed(* trunk Scripts Bash Functions Verify::) --- +@end menu + +@subsection See also + +@menu +* trunk Scripts Bash:: +@comment --- Removed(* trunk Scripts Bash Locale::) --- +@end menu diff --git a/Manuals/Filesystem/trunk/Scripts/Bash/cli/Functions/Help.texi b/Manuals/Filesystem/trunk/Scripts/Bash/cli/Functions/Help.texi new file mode 100644 index 0000000..fb39647 --- /dev/null +++ b/Manuals/Filesystem/trunk/Scripts/Bash/cli/Functions/Help.texi @@ -0,0 +1,22 @@ +@subsection Goals + +@itemize +@item ... +@end itemize + +@subsection Description + +@itemize +@item ... +@end itemize + +@subsection Usage + +@itemize +@item ... +@end itemize + +@subsection See also + +@menu +@end menu diff --git a/Manuals/Filesystem/trunk/Scripts/Bash/cli/Functions/Html.texi b/Manuals/Filesystem/trunk/Scripts/Bash/cli/Functions/Html.texi new file mode 100644 index 0000000..fb39647 --- /dev/null +++ b/Manuals/Filesystem/trunk/Scripts/Bash/cli/Functions/Html.texi @@ -0,0 +1,22 @@ +@subsection Goals + +@itemize +@item ... +@end itemize + +@subsection Description + +@itemize +@item ... +@end itemize + +@subsection Usage + +@itemize +@item ... +@end itemize + +@subsection See also + +@menu +@end menu diff --git a/Manuals/Filesystem/trunk/Scripts/Bash/cli/Functions/Locale.texi b/Manuals/Filesystem/trunk/Scripts/Bash/cli/Functions/Locale.texi new file mode 100644 index 0000000..bf264c9 --- /dev/null +++ b/Manuals/Filesystem/trunk/Scripts/Bash/cli/Functions/Locale.texi @@ -0,0 +1,85 @@ +@subsection Goals + +@itemize +@item ... +@end itemize + +@subsection Description + +This command looks for @samp{.sh} files inside Bash directory and +extracts translatable strings from files, using @command{xgettext} +command, in order to create a portable object template +(@file{centos-art.sh.pot}) file for them. + +With the @file{centos-art.sh.pot} file up to date, the +@command{centos-art} command removes the temporal list of files sotred +inside @file{/tmp} directory and checks the current language of your +user's session to create a portable object file for it, in the +location @file{$CLI_LANG/$CLI_LANG.po}. + +The @var{CLI_LANG} variable discribes the locale language used to +output messages inside @command{centos-art} command. The locale +language used inside @command{centos-art} command is taken from the +@env{LANG} environment variable. The @var{CLI_LANG} variable has the +@samp{LL_CC} format, where @samp{LL} is a language code from the +ISO-639 standard, and @samp{CC} a country code from the ISO-3166 +standard. + +The @env{LANG} environment variable is set when you do log in to your +system. If you are using a graphical session, change language to your +native language and do login. That would set and exoprt the @env{LANG} +environment variable to the correct value. On the other side, if you +are using a text session edit your @file{~/.bash_profile} file to set +and export the @env{LANG} environment variable to your native locale +as defines the @command{locale -a} command output; do logout, and do +login again. + +At this point, the @env{LANG} environment variable has the appropriate +value you need, in order to translate @command{centos-art.sh} messages +to your native language (the one set in @env{LANG} environment +variable). + +With the @file{$CLI_LANG/$CLI_LANG.po} file up to date, the +@command{centos-art} opens it for you to update translation strings. +The @command{centos-art} command uses the value of @var{EDITOR} +environment variable to determine your favorite text editor. If no +value is defined on @var{EDITOR}, the @file{/usr/bin/vim} text editor +is used as default. + +When you finishd PO file edition and quit text editor, the +@command{centos-art} command creates the related machine object in the +location @file{$CLI_LANG/LC_MESSAGES/$TEXTDOMAIN.mo}. + +At this point, all translations you made in the PO file should be +available to your language when runing @command{centos-art.sh} script. + +In order to make the @command{centos-art.sh} internationalization, the +@command{centos-art.sh} script was modified as described in the +@command{gettext} info documentation (@command{info gettext}). You +can find such modifications in the following files: + +@itemize +@item @file{trunk/Scripts/Bash/initFunctions.sh} +@item @file{trunk/Scripts/Bash/Functions/Help/cli_localeMessages.sh} +@item @file{trunk/Scripts/Bash/Functions/Help/cli_localeMessagesStatus.sh} +@end itemize + +@itemize +@item ... +@end itemize + +@subsection Usage + +@table @samp +@item centos-art locale --edit +Use this command to translate command-line interface output messages +in the current system locale you are using (as specified in @env{LANG} +environment variable). +@item centos-art locale --list +Use this command to see the command-line interface locale report. +@end table + +@subsection See also + +@menu +@end menu diff --git a/Manuals/Filesystem/trunk/Scripts/Bash/cli/Functions/Manual.texi b/Manuals/Filesystem/trunk/Scripts/Bash/cli/Functions/Manual.texi new file mode 100644 index 0000000..fb39647 --- /dev/null +++ b/Manuals/Filesystem/trunk/Scripts/Bash/cli/Functions/Manual.texi @@ -0,0 +1,22 @@ +@subsection Goals + +@itemize +@item ... +@end itemize + +@subsection Description + +@itemize +@item ... +@end itemize + +@subsection Usage + +@itemize +@item ... +@end itemize + +@subsection See also + +@menu +@end menu diff --git a/Manuals/Filesystem/trunk/Scripts/Bash/cli/Functions/Path.texi b/Manuals/Filesystem/trunk/Scripts/Bash/cli/Functions/Path.texi new file mode 100644 index 0000000..a7c6c55 --- /dev/null +++ b/Manuals/Filesystem/trunk/Scripts/Bash/cli/Functions/Path.texi @@ -0,0 +1,327 @@ +@subsection Goals + +This section exists to organize files related to @code{path} +functiontionality. The @code{path} functionality standardizes +movement, syncronization, branching, tagging, and general file +maintainance inside the repository. + +@subsection Description + +@emph{''CentOS like trees, has roots, trunk, branches, leaves and +flowers. Day by day they work together in freedom, ruled by the laws +of nature and open standards, to show the beauty of its existence.''} + +@subsubsection Repository layout + +The repository layout describes organization of files and directories +inside the repository. The repository layout provides the standard +backend required for automation scripts to work correctly. If such +layout changes unexpectedly, automation scripts may confuse themselves +and stop doing what we expect from them to do. + +As convenction, inside CentOS Artwork Repository, we organize files +and directories related to CentOS corporate visual identity under +three top level directories named: @file{trunk/}, @file{branches/}, +and @file{tags/}. + +The @file{trunk/} directory (@pxref{trunk}) organizes the main +development line of CentOS corporate visual identity. Inside +@file{trunk/} directory structure, the CentOS corporate visual +identity concepts are implemented using directories. There is one +directory level for each relevant concept inside the repository. The +@file{trunk/} directory structure is mainly used to perform +development tasks related to CentOS corporate visual identity. + +The @file{branches/} directory (@pxref{branches}) oranizes parallel +development lines to @file{trunk/} directory. The @file{branches/} +directory is used to set points in time where develpment lines are +devided one from another taking separte and idependent lives that +share a common past from the point they were devided on. The +@file{branches/} directory is mainly used to perform quality assurance +tasks related to CentOS corporate visual identity. + +The @file{tags/} directory (@pxref{tags}) organizes parallel frozen +lines to @file{branches/} directory. The parallel frozen lines are +immutable, nothing change inside them once they has been created. The +@file{tags/} directory is mainly used to publish final releases of +CentOS corporate visual identity. + +The CentOS Artwork Repository layout is firmly grounded on a +Subversion base. Subversion (@url{http://subversion.tigris.org}) is a +version control system, which allows you to keep old versions of files +and directories (usually source code), keep a log of who, when, and +why changes occurred, etc., like CVS, RCS or SCCS. Subversion keeps a +single copy of the master sources. This copy is called the source +``repository''; it contains all the information to permit extracting +previous versions of those files at any time. + +@subsubsection Repository name convenctions + +Repository name convenctions help us to maintain consistency of names +inside the repository. + +Repository name convenctions are applied to files and directories +inside the repository layout. As convenction, inside the repository +layout, file names are all written in lowercase +(@samp{01-welcome.png}, @samp{splash.png}, @samp{anaconda_header.png}, +etc.) and directory names are all written capitalized (e.g., +@samp{Identity}, @samp{Themes}, @samp{Motifs}, @samp{TreeFlower}, +etc.). + +Repository name convenctions are implemented inside the +@code{cli_getRepoName} function of @file{centos-art.sh} script. With +@code{cli_getRepoName} function we reduce the amount of commands and +convenctions to remember, concentrating them in just one single place +to look for fixes and improvements. + +@subsubsection Repository work flow + +Repository work flow describes the steps and time intervals used to +produce CentOS corporate visual identity inside CentOS Artwork +Repository. + +To illustrate repository work flow let's consider themes' development +cycle. + +Initially, we start working themes on their trunk development line +(e.g., @file{trunk/Identity/Themes/Motifs/TreeFlower/}), here we +organize information that cannot be produced automatically (i.e., +background images, concepts, color information, screenshots, etc.). + +Later, when theme trunk development line is considered ``ready'' for +implementation (e.g., all required backgrounds have been designed), +we create a branch for it (e.g., +@file{branches/Identity/Themes/Motifs/TreeFlower/1/}). Once the +branch has been created, we forget that branch and continue working +the trunk development line while others (e.g., an artwork quality +assurance team) test the new branch for tunning it up. + +Once the branch has been tunned up, and considered ``ready'' for +release, it is freezed under @file{tags/} directory (e.g., +@file{tags/Identity/Themes/Motifs/TreeFower/1.0/}) for packagers, +webmasters, promoters, and anyone who needs images from that CentOS +theme the tag was created for. + +Both branches and tags, inside CentOS Artwork Repository, use +numerical values to identify themselves under the same location. +Branches start at one (i.e., @samp{1}) and increment one unit for each +branch created from the same trunk development line. Tags start at +zero (i.e., @samp{0}) and increment one unit for each tag created from +the same branch development line. + +@quotation +@strong{Convenction} Do not freeze trunk development lines using tags +directly. If you think you need to freeze a trunk development line, +create a branch for it and then freeze that branch instead. +@end quotation + +The trunk development line may introduce problems we cannot see +immediatly. Certainly, the high changable nature of trunk development +line complicates finding and fixing such problems. On the other hand, +the branched development lines provide a more predictable area where +only fixes/corrections to current content are commited up to +repository. + +If others find and fix bugs inside the branched development line, we +could merge such changes/experiences back to trunk development line +(not visversa) in order for future branches, created from trunk, to +benefit. + +Time intervals used to create branches and tags may vary, just as +different needs may arrive. For example, consider the release schema +of CentOS distribution: one major release every 2 years, security +updates every 6 months, support for 7 years long. Each time a CentOS +distribution is released, specially if it is a major release, there is +a theme need in order to cover CentOS distribution artwork +requirements. At this point, is where CentOS Artwork Repository comes +up to scene. + +Before releasing a new major release of CentOS distribution we create +a branch for one of several theme development lines available inside +the CentOS Artwork Repository, perform quality assurance on it, and +later, freeze that branch using tags. Once a the theme branch has been +frozen (under @file{tags/} directory), CentOS Packagers (the persons +whom build CentOS distribution) can use that frozen branch as source +location to fulfill CentOS distribution artwork needs. The same +applies to CentOS Webmasters (the persons whom build CentOS websites), +and any other visual manifestation required by the project. + +@subsubsection Parallel directories + +Inside CentOS Artwork Repository, parallel directories are simple +directory entries built from a common parent directory and placed in a +location different to that, the common parent directory is placed on. +Parallel directories are useful to create branches, tags, +translations, documentation, pre-rendering configuration script, and +similar directory structures. + +Parallel directories take their structure from one unique parent +directory. Inside CentOS Artwork Repository, this unique parent +directory is under @file{trunk/Identity} location. The +@file{trunk/Identity} location must be considered the reference for +whatever information you plan to create inside the repository. + +In some circumstances, parallel directories may be created removing +uncommon information from their paths. Uncommon path information +refers to those directory levels in the path which are not common for +other parallel directories. For example, when rendering +@file{trunk/Identity/Themes/Motifs/TreeFlower/Distro} directory +structure, the @file{centos-art.sh} script removes the +@file{Motifs/TreeFlower/} directory levels from path, in order to +build the parallel directory used to retrived translations, and +pre-rendering configuration scripts required by @code{render} +functionality. + +Another example of parallel directory is the documentation structure +created by @code{manual} functionality. This time, +@file{centos-art.sh} script uses parallel directory information with +uncommon directory levels to build the documentation entry required by +Texinfo documentation system, inside the repository. + +Othertimes, parallel directories may add uncommon information to their +paths. This is the case we use to create branches and tags. When we +create branches and tags, a numerical identifier is added to parallel +directory structure path. The place where the numerical identifier is +set on is relevant to corporate visual identity structure and should +be carefully considered where it will be. + +When one parent directory changes, all their related parallel +directories need to be changed too. This is required in order for +parallel directories to retain their relation with the parent +directory structure. In the other hand, parallel directories should +never be modified under no reason but to satisfy the relation to their +parent directory structure. Liberal change of parallel directories +may suppresses the conceptual idea they were initially created for; +and certainly, things may stop working the way they should do. + +@subsubsection Syncronizing path information + +Parallel directories are very useful to keep repository organized but +introduce some complications. For instance, consider what would +happen to functionalities like @code{manual} (@samp{trunk Scripts Bash +Functions Manual}) that rely on parent directory structures to create +documentation entries (using parallel directory structures) if one of +those parent directory structures suddenly changes after the +documentation entry has been already created for it? + +In such cases, functionalities like @code{manual} may confuse +themselves if path information is not updated to reflect the relation +with its parent directory. Such functionalities work with parent +directory structure as reference; if a parent directory changes, the +functionalities dont't even note it because they work with the last +parent directory structure available in the repository, no matter what +it is. + +In the specific case of documentation (the @code{manual} +functionality), the problem mentioned above provokes that older parent +directories, already documented, remain inside documentation directory +structures as long as you get your hands into the documentation +directory structure (@file{trunk/Manuals}) and change what must be +changed to match the new parent directory structure. + +There is no immediate way for @code{manual}, and similar +functionalities that use parent directories as reference, to know when +and how directory movements take place inside the repository. Such +information is available only when the file movement itself takes +place inside the repository. So, is there, at the moment of moving +files, when we need to syncronize parallel directories with their +unique parent directory structure. + +@quotation +@strong{Warning} There is not support for URL reference inside +@file{centos-art.sh} script. The @file{centos-art.sh} script is +designed to work with local files inside the working copy only. +@end quotation + +As CentOS Artwork Repository is built over a version control system, +file movements inside the repository are considered repository +changes. In order for these repository changes to be versioned, we +need to, firstly, add changes into the version control system, commit +them, and later, perform movement actions using version control system +commands. This configuration makes possible for everyone to know about +changes details inside the repository; and if needed, revert or update +them back to a previous revision. + +Finally, once all path information has been corrected, it is time to +take care of information inside the files. For instance, considere +what would happen if you make a reference to a documentation node, and +later the documentation node you refere to is deleted. That would make +Texinfo to produce error messages at export time. So, the +@file{centos-art.sh} script needs to know when such changes happen, in +a way they could be noted and handled without producing errors. + +@subsubsection What is the right place to store it? + +Occasionly, you may find that new corporate visual identity components +need to be added to the repository. If that is your case, the first +question you need to ask yourself, before start to create directories +blindly all over, is: What is the right place to store it? + +The CentOS Community different free support vains (see: +@url{http://wiki.centos.org/GettingHelp}) are the best place to find +answers to your question, but going there with hands empty is not good +idea. It may give the impression you don't really care about. Instead, +consider the following suggestions to find your own comprehension and +so, make your propositions based on it. + +When we are looking for the correct place to store new files, to bear +in mind the corporate visual identity structure used inside the CentOS +Artwork Repository (@pxref{trunk Identity}) would be probaly the best +advice we could offer, the rest is just matter of choosing appropriate +names. To illustrate this desition process let's consider the +@file{trunk/Identity/Themes/Motifs/TreeFlower} directory as example. +It is the trunk development line of @emph{TreeFlower} artistic motif. +Artistic motifs are considered part of themes, which in turn are +considered part of CentOS corporate visual identity. + +When building parent directory structures, you may find that reaching +an acceptable location may take some time, and as it uses to happen +most of time; once you've find it, that may be not a definite +solution. There are many concepts that you need to play with, in +order to find a result that match the conceptual idea you try to +implement in the new directory location. To know which these concepts +are, split the location in words and read its documentation entry from +less specific to more specific. + +For example, the @file{trunk/Identity/Themes/Motifs/TreeFlower} +location evolved through several months of contant work and there is +no certain it won't change in the future, even it fixes quite well the +concept we are trying to implement. The concepts used in +@file{trunk/Identity/Themes/Distro/Motifs/TreeFlower} location are +described in the following commands, respectively: + +@verbatim +centos-art manual --read=turnk/ +centos-art manual --read=turnk/Identity/ +centos-art manual --read=turnk/Identity/Themes/ +centos-art manual --read=turnk/Identity/Themes/Motifs/ +centos-art manual --read=turnk/Identity/Themes/Motifs/TreeFlower/ +@end verbatim + +Other location concepts can be found similary as we did above, just +change the location we used above by the one you are trying to know +concepts for. + +@subsection Usage + +@table @command +@item centos-art path --copy='SRC' --to='DST' + +Copy @option{SRC} to @option{DST} and schedule @option{DST} for +addition (with history). In this command, @file{SRC} and @file{DST} +are both working copy (WC) entries. + +@item centos-art path --delete='SRC' + +Delete @option{DST}. In order for this command to work the file or +directory you intend to delete should be under version control first. +In this command, @file{SRC} is a working copy (WC) entry. + +@end table + +@subsection See also + +@menu +* trunk Scripts Bash:: +@comment --- Removed(* trunk Scripts Bash Functions::) --- +@end menu diff --git a/Manuals/Filesystem/trunk/Scripts/Bash/cli/Functions/Render.texi b/Manuals/Filesystem/trunk/Scripts/Bash/cli/Functions/Render.texi new file mode 100644 index 0000000..7dfe2c5 --- /dev/null +++ b/Manuals/Filesystem/trunk/Scripts/Bash/cli/Functions/Render.texi @@ -0,0 +1,736 @@ +The @code{render} functionality exists to produce both identity and +translation files on different levels of information (i.e., different +languages, release numbers, architectures, etc.). + +The @code{render} functionality relies on ``renderable directory +structures'' to produce files. Renderable directory structures can be +either ``identity directory structures'' or ``translation directory +structures'' with special directories inside. + +@subsection Renderable identity directory structures + +Renderable identity directory structures are the starting point of +identity rendition. Whenever we want to render a component of CentOS +corporate visual identity, we need to point @file{centos-art.sh} to a +renderable identity directory structure. If such renderable identity +directory structure doesn't exist, then it is good time to create it. + +Inside the working copy, one renderable identity directory structures +represents one visual manifestation of CentOS corporate visual +identity, or said differently, each visual manifestation of CentOS +corporate visual identity should have one renderable identity +directory structure. + +Inside renderable identity directory structures, @file{centos-art.sh} +can render both image-based and text-based files. Specification of +whether a renderable identity directory structure produces image-based +or text-based content is a configuration action that takes place in +the pre-rendition configuration script of that renderable identity +directory structure. + +Inside renderable identity directory structures, content production is +organized in different configurations. A content production +configuration is a unique combination of the components that make an +identity directory structure renderable. One content production +configuration does one thing only (e.g., to produce untranslated +images), but it can be extended (e.g., adding translation files) to +achieve different needs (e.g., to produce translated images). + +@subsubsection Design template without translation + +The design template without translation configuration is based on a +renderable identity directory structure with an empty translation +directory structure. In this configuration, one design template +produces one untranslated file. Both design templates and final +untranslated files share the same file name, but they differ one +another in file-type and file-extension. + +For example, to produce images without translations (there is no much +use in producing text-based files without translations), consider the +following configuration: + +@table @strong +@item One renderable identity directory structure: + +In this example we used @file{Identity/Path/To/Dir} as the identity +component we want to produce untranslated images for. Identity +components can be either under @file{trunk/} or @file{branches/} +directory structure. + +The identity component (i.e., @file{Identity/Path/To/Dir}, in this +case) is also the bond component we use to connect the identity +directory structures with their respective auxiliar directories (i.e., +translation directory structres and pre-rendition configuration +structures). The bond component is the path convenction that +@file{centos-art.sh} uses to know where to look for related +translations, configuration scripts and whatever auxiliar thing a +renderable directory structure may need to have. + +@verbatim + | The bond component + |----------------->| +trunk/Identity/Path/To/Dir <-- Renderable identity directory structure. +|-- Tpl <-- Design template directory. +| `-- file.svg <-- Design template file. +`-- Img <-- Directory used to store final files. + `-- file.png <-- Final image-based file produced from + design template file. +@end verbatim + +Inside design template directory, design template files are based on +@acronym{SVG,Scalable Vector Graphics} and use the extension +@code{.svg}. Design template files can be organized using several +directory levels to create a simple but extensible configuration, +specially if translated images are not required. + +In order for @acronym{SVG,Scalable Vector Graphics} files to be +considered ``design template'' files, they should be placed under the +design template directory and to have set a @code{CENTOSARTWORK} +object id inside. + +The @code{CENTOSARTWORK} word itself is a convenction name we use to +define which object/design area, inside a design template, the +@file{centos-art.sh} script will use to export as +@acronym{PNG,Portable Network Graphic} image at rendition time. +Whithout such object id specification, the @file{centos-art.sh} script +cannot know what object/design area you (as designer) want to export +as @acronym{PNG,Portable Network Graphic} image file. + +@quotation +@strong{Note} At rendition time, the content of @file{Img/} directory +structure is produced by @file{centos-art.sh} automatically. +@end quotation + +When a renderable identity directory structure is configured to +produce image-based content, @file{centos-art.sh} produces +@acronym{PNG,Portable Network Graphics} files with the @code{.png} +extension. Once the base image format has been produced, it is +possible for @file{centos-art.sh} to use it in order to automatically +create other image formats that may be needed (--- @strong{Removed}(pxref:trunk Scripts +Bash Functions Render Config) ---). + +Inside the working copy, you can find an example of ``design template +without translation'' configuration at @file{trunk/Identity/Models/}. + +@xref{trunk Identity}, for more information. + +@item One translation directory structure: + +In order for an identity entry to be considered an identity renderable +directory structure, it should have a translation entry. The content +of the translation entry is relevant to determine how to process the +identity renderable directory entry. + +If the translation entry is empty (i.e., there is no file inside it), +@file{centos-art.sh} interprets the identity renderable directory +structure as a ``design templates without translation'' configuration. + +@verbatim + | The bond component + |----------------->| +trunk/Translations/Identity/Path/To/Dir +`-- (empty) +@end verbatim + +If the translation entry is not empty, @file{centos-art.sh} can +interpret the identity renderable directory structure as one of the +following configurations: ``design template with translation +(one-to-one)'' or ``design template with translation (optimized)''. +Which one of these configurations is used depends on the value +assigned to the matching list (@var{MATCHINGLIST}) variable in the +pre-rendition configuration script of the renderable identity +directory structure we are producing images for. + +If the matching list variable is empty (as it is by default), then +``design template with translation (one-to-one)'' configuration is +used. In this configuration it is required that both design templates +and translation files have the same file names. This way, @emph{one} +translation files is applied to @emph{one} design template, to produce +@emph{one} translated image. + +If the matching list variable is not empty (because you redefine it in +the pre-rendition configuration script), then ``design template with +translation (optimized)'' configuration is used instead. In this +configuration, design templates and translation files don't need to +have the same names since such name relationship between them is +specified in the matching list properly. + +--- @strong{Removed}(xref:trunk Translations) ---, for more information. + +@item One pre-rendition configuration script: + +In order to make an identity directory structure renderable, a +pre-rendition configuration script should exist for it. The +pre-rendition configuration script specifies what type of rendition +does @file{centos-art.sh} will perform over the identity directory +structure and how does it do that. + +@verbatim + | The bond component + |----------------->| +trunk/Scripts/Bash/Functions/Render/Config/Identity/Path/To/Dir +`-- render.conf.sh +@end verbatim + +In this configuration the pre-rendition configuration script +(@file{render.conf.sh}) would look like the following: + +@verbatim +function render_loadConfig { + + # Define rendition actions. + ACTIONS[0]='BASE:renderImage' + +} +@end verbatim + +Since translation directory structure is empty, @file{centos-art.sh} +assumes a ``design template without translation'' configuration to +produce untranslated images. + +To produce untranslated images, @file{centos-art.sh} takes one design +template and creates one temporal instance from it. Later, +@file{centos-art.sh} uses the temporal design template instance as +source file to export the final untranslated image. The action of +exporting images from @acronym{SVG,Scalable Vector Graphics} to +@acronym{PNG,Portable Network Graphics} is possible thanks to +Inkscape's command-line interface and the @code{CENTOSARTWORK} object +id we previously set inside design templates. + +@verbatim +centos-art.sh render --identity=trunk/Identity/Path/To/Dir +------------------------------------------------- +0 | Execute centos-art.sh on renderable identity directory structure. +--v---------------------------------------------- +trunk/Identity/Path/To/Dir/Tpl/file.svg +------------------------------------------------- +1 | Create instance from design template. +--v---------------------------------------------- +/tmp/centos-art.sh-a07e824a-5953-4c21-90ae-f5e8e9781f5f-file.svg +------------------------------------------------- +2 | Render untranslated image from design template instance. +--v---------------------------------------------- +trunk/Identity/NewDir/Img/file.png +------------------------------------------------- +3 | Remove design template instance. +@end verbatim + +Finally, when the untranslated image has been created, the temporal +design template instance is removed. At this point, +@file{centos-art.sh} takes the next design template and repeats the +whole production flow once again (design template by design template), +until all design templates be processed. + +--- @strong{Removed}(xref:trunk Scripts Bash Functions Render Config) ---, for more +information. +@end table + +@subsubsection Design template with translation (one-to-one) + +Producing untranslated images is fine in many cases, but not always. +Sometimes it is required to produce images in different languages and +that is something that untrasnlated image production cannot achieve. +However, if we fill its empty translation entry with translation files +(one for each design template) we extend the production flow from +untranslated image production to translated image production. + +In order for @file{centos-art.sh} to produce images correctly, each +design template should have one translation file and each translation +file should have one design template. Otherwise, if there is a +missing design template or a missing translation file, +@file{centos-art.sh} will not produce the final image related to the +missing component. + +In order for @file{centos-art.sh} to know which is the relation +between translation files and design templates the translation +directory structure is taken as reference. For example, the +@file{trunk/Translations/Identity/Path/To/Dir/file.sed} translation +file does match @file{trunk/Identity/Path/To/Dir/Tpl/file.svg} design +template, but it doesn't match +@file{trunk/Identity/Path/To/Dir/File.svg} or +@file{trunk/Identity/Path/To/Dir/Tpl/File.svg} or +@file{trunk/Identity/Path/To/Dir/Tpl/SubDir/file.svg} design +templates. + +The pre-rendition configuration script used to produce untranslated +images is the same we use to produce translated images. There is no +need to modify it. So, as we are using the same pre-rendition +configuration script, we can say that translated image production is +somehow an extended/improved version of untranslated image production. + +@quotation +@strong{Note} If we use no translation file in the translation entry +(i.e., an empty directory), @file{centos-art.sh} assumes the +untranslated image production. If we fill the translation entry with +translation files, @file{centos-art.sh} assumes the translated image +production. +@end quotation + +To produce final images, @file{centos-art.sh} applies one translation +file to one design template and produce a translated design template +instance. Later, @file{centos-art.sh} uses the translated template +instance to produce the translated image. Finally, when the translated +image has been produced, @file{centos-art.sh} removes the translated +design template instance. This production flow is repeated for each +translation file available in the translatio entry. + +@verbatim +centos-art.sh render --identity=trunk/Identity/Path/To/Dir +------------------------------------------------- +0 | Execute centos-art.sh on directory structure. +--v---------------------------------------------- +trunk/Translations/Identity/Path/To/Dir/file.sed +------------------------------------------------- +1 | Apply translation to design template. +--v---------------------------------------------- +trunk/Identity/Path/To/Dir/Tpl/file.svg +------------------------------------------------- +2 | Create design template instance. +--v---------------------------------------------- +/tmp/centos-art.sh-a07e824a-5953-4c21-90ae-f5e8e9781f5f-file.svg +------------------------------------------------- +3 | Render PNG image from template instance. +--v---------------------------------------------- +trunk/Identity/NewDir/Img/file.png +------------------------------------------------- +4 | Remove design template instance. +@end verbatim + +@subsubsection Design template with translation (optimized) + +Producing translated images satisfies almost all our production images +needs, but there is still a pitfall in them. In order to produce +translated images as in the ``one-to-one'' configuration describes +previously, it is required that one translation file has one design +template. That's useful in many cases, but what would happen if we +need to apply many different translation files to the same design +template? Should we have to duplicate the same design template file +for each translation file, in order to satisfy the ``one-to-one'' +relation? What if we need to assign translation files to design +templates arbitrarily? + +Certenly, that's something the ``one-to-one'' configuration cannot +handle. So, that's why we had to ``optimize'' it. The optimized +configuration consists on using a matching list (@var{MATCHINGLIST}) +variable that specifies the relationship between translation files and +design templates in an arbitrary way. Using such matching list between +translation files and design templates let us use as many assignment +combinations as translation files and design templates we are working +with. + +The @var{MATCHINGLIST} variable is set in the pre-rendition +configuration script of the component we want to produce images for. +By default, the @var{MATCHINGLIST} variable is empty which means no +matching list is used. Otherwise, if @var{MATCHINGLIST} variable has a +value different to empty value then, @file{centos-art.sh} interprets +the matching list in order to know how translation files are applied +to design templates. + +For example, consider the following configuration: + +@table @strong +@item One entry under @file{trunk/Identity/}: + +In this configuration we want to produce three images using a +paragraph-based style, controlled by @file{paragraph.svg} design +template; and one image using a list-based style, controlled by +@file{list.svg} design template. + +@verbatim +trunk/Identity/Path/To/Dir +|-- Tpl +| |-- paragraph.svg +| `-- list.svg +`-- Img + |-- 01-welcome.png + |-- 02-donate.png + |-- 03-docs.png + `-- 04-support.png +@end verbatim + +@item One entry under @file{trunk/Translations/}: + +In order to produce translated images we need to have one translation +file for each translated image we want to produce. Notice how +translation names do match final image file names, but how translation +names do not match design template names. When we use matching list +there is no need for translation files to match the names of design +templates, such name relation is set inside the matching list itself. + +@verbatim +trunk/Translations/Identity/Path/To/Dir +|-- 01-welcome.sed +|-- 02-donate.sed +|-- 03-docs.sed +`-- 04-support.sed +@end verbatim + +@item One entry under @file{trunk/trunk/Scripts/Bash/Functions/Render/Config/}: + +In order to produce different translated images using specific design +templates, we need to specify the relation between translation files +and design templates in a way that @file{centos-art.sh} could know +exactly what translation file to apply to what design template. This +relation between translation files and design templates is set using +the matching list @var{MATCHINGLIST} variable inside the pre-rendition +configuration script of the component we want to produce images for. + +@verbatim +trunk/Scripts/Bash/Functions/Render/Config/Identity/Path/To/Dir +`-- render.conf.sh +@end verbatim + +In this configuration the pre-rendition configuration script +(@file{render.conf.sh}) would look like the following: + +@verbatim +function render_loadConfig { + + # Define rendition actions. + ACTIONS[0]='BASE:renderImage' + + # Define matching list. + MATCHINGLIST="\ + paragraph.svg:\ + 01-welcome.sed\ + 02-donate.sed\ + 04-support.sed + list.svg:\ + 03-docs.sed + " + +} +@end verbatim + +As result, @file{centos-art.sh} will produce @file{01-welcome.png}, +@file{02-donate.png} and @file{04-support.png} using the +paragraph-based design template, but @file{03-docs.png} using the +list-based design template. +@end table + +@subsubsection Design template with translation (optimized+flexibility) + +In the production models we've seen so far, there are design templates +to produce untranslated images and translation files which combiend +with design templates produce translated images. That may seems like +all our needs are covered, doesn't it? Well, it @emph{almost} does. + +Generally, we use design templates to define how final images will +look like. Generally, each renderable directory structure has one +@file{Tpl/} directory where we organize design templates for that +identity component. So, we can say that there is only one unique +design template definition for each identity component; or what is the +same, said differently, identity components can be produced in one way +only, the way its own design template directory specifies. This is +not enough for theme production. It is a limitation, indeed. + +Initially, to create one theme, we created one renderable directory +structure for each theme component. When we found ourselves with many +themes, and components inside them, it was obvious that the same +design model was duplicated inside each theme. As design models were +independently one another, if we changed one theme's design model, +that change was useless to other themes. So, in order to reuse design +model changes, we unified design models into one common directory +structure. + +With design models unified in a common structure, another problem rose +up. As design models also had the visual style of theme components, +there was no difference between themes, so there was no apparent need +to have an independent theme directory structure for each different +theme. So, it was also needed to separate visual styles from design +models. + +At this point there are two independent worklines: one directory +structure to store design models (the final image characteristics +[i.e., dimensions, translation markers, etc.]) and one directory +structure to store visual styles (the final image visual style [i.e., +the image look and feel]). So, it is possible to handle both +different design models and different visual styles independtly one +another and later create combinations among them using +@file{centos-art.sh}. + +For example, consider the following configuration: + +@table @strong +@item One entry under @file{trunk/Identity/Themes/Models/}: + +The design model entry exists to organize design model files (similar +to design templates). Both design models and design templates are very +similar; they both should have the @code{CENTOSARTWORK} export id +present to identify the exportation area, translation marks, etc. +However, design models do use dynamic backgrounds inclusion while +design templates don't. + +@verbatim + THEMEMODEL | | The bond component + |<----| |--------------------->| +trunk/Identity/Themes/Models/Default/Distro/Anaconda/Progress/ +|-- paragraph.svg +`-- list.svg +@end verbatim + +Inisde design models, dynamic backgrounds are required in order for +different artistic motifs to reuse common design models. Firstly, in +order to create dynamic backgrounds inside design models, we import a +bitmap to cover design model's background and later, update design +model's path information to replace fixed values to dynamic values. + +@item One entry under @file{trunk/Identity/Themes/Motifs/}: + +The artistic motif entry defines the visual style we want to produce +images for, only. Final images (i.e., those built from combining both +design models and artistic motif backrounds) are not stored here, but +under branches directory structure. In the artistic motif entry, we +only define those images that cannot be produced automatically by +@file{centos-art.sh} (e.g., Backgrounds, Color information, +Screenshots, etc.). + +@verbatim + Artistic motif name | | Artistic motif backgrounds + |<-------| |-------->| +trunk/Identity/Themes/Motifs/TreeFlower/Backgrounds/ +|-- Img +| |-- Png +| | |-- 510x300.png +| | `-- 510x300-final.png +| `-- Jpg +| |-- 510x300.jpg +| `-- 510x300-final.jpg +|-- Tpl +| `-- 510x300.svg +`-- Xcf + `-- 510x300.xcf +@end verbatim + +@item One entry under @file{trunk/Translations/}: + +The translation entry specifies, by means of translation files, the +language-specific information we want to produce image for. When we +create the translation entry we don't use the name of neither design +model nor artistic motif, just the design model component we want to +produce images for. + +@verbatim + | The bond component + |--------------------->| +trunk/Translations/Identity/Themes/Distro/Anaconda/Progress/ +`-- 5 + |-- en + | |-- 01-welcome.sed + | |-- 02-donate.sed + | `-- 03-docs.sed + `-- es + |-- 01-welcome.sed + |-- 02-donate.sed + `-- 03-docs.sed +@end verbatim + +@item One entry under @file{trunk/Scripts/Bash/Functions/Render/Config/}: + +There is one pre-rendition configuration script for each theme +component. So, each time a theme component is rendered, its +pre-rendition configuration script is evaluated to teach +@file{centos-art.sh} how to render the component. + +@verbatim +trunk/Scripts/Bash/Functions/Render/Config/Identity/Themes/Distro/Anaconda/Progress/ +`-- render.conf.sh +@end verbatim + +In this configuration the pre-rendition configuration script +(@file{render.conf.sh}) would look like the following: + +@verbatim +function render_loadConfig { + + # Define rendition actions. + ACTIONS[0]='BASE:renderImage' + + # Define matching list. + MATCHINGLIST="\ + paragraph.svg:\ + 01-welcome.sed\ + 02-donate.sed + list.svg:\ + 03-docs.sed + " + + # Deifne theme model. + THEMEMODEL='Default' + +} +@end verbatim +@end table + +The production flow of ``optimize+flexibility'' configuration@dots{} +@subsection Renderable translation directory structures + +Translation directory structures are auxiliar structures of renderable +identity directory structures. There is one translation directory +structure for each renderable identity directory structure. Inside +translation directory structures we organize translation files used by +renderable identity directory structures that produce translated +images. Renderable identity directory structures that produce +untranslated images don't use translation files, but they do use a +translation directory structure, an empty translation directory +structure, to be precise. + +In order to aliviate production of translation file, we made +translation directory structures renderable adding a template +(@file{Tpl/}) directory structure to handle common content inside +translation files. This way, we work on translation templates and +later use @file{centos-art.sh} to produce specific translation files +(based on translation templates) for different information (e.g., +languages, release numbers, architectures, etc.). + +If for some reason, translation files get far from translation +templates and translation templates become incovenient to produce such +translation files then, care should be taken to avoid replacing the +content of translation files with the content of translation templates +when @file{centos-art.sh} is executed to produce translation files +from translation templates. + +Inside renderable translation directory structures, +@file{centos-art.sh} can produce text-based files only. + +@subsection Copying renderable directory structures + +A renderable layout is formed by design models, design images, +pre-rendition configuration scripts and translations files. This way, +when we say to duplicate rendition stuff we are saying to duplicate +these four directory structures (i.e., design models, design images, +pre-rendition configuration scripts, and related translations files). + +When we duplicate directories, inside `trunk/Identity' directory +structure, we need to be aware of renderable layout described above +and the source location used to perform the duplication action. The +source location is relevant to centos-art.sh script in order to +determine the required auxiliar information inside directory +structures that need to be copied too (otherwise we may end up with +orphan directory structures unable to be rendered, due the absence of +required information). + +In order for a renderable directory structure to be valid, the new +directory structure copied should match the following conditions: + +@enumerate +@item To have a unique directory structure under +@file{trunk/Identity}, organized by any one of the above +organizational designs above. + +@item To have a unique directory structure under +@file{trunk/Translations} to store translation files. + +@item To have a unique directory structure under +@file{trunk/Scripts/Bash/Functions/Render/Config} to set pre-rendition +configuration script. +@end enumerate + +As convenction, the @code{render_doCopy} function uses +@file{trunk/Identity} directory structure as source location. Once +the @file{trunk/Identity} directory structure has been specified and +verified, the related path information is built from it and copied +automatically to the new location specified by @var{FLAG_TO} variable. + +Design templates + No translation: + +Command: +- centos-art render --copy=trunk/Identity/Path/To/Dir --to=trunk/Identity/NewPath/To/Dir + +Sources: +- trunk/Identity/Path/To/Dir +- trunk/Translations/Identity/Path/To/Dir +- trunk/Scripts/Bash/Functions/Render/Config/Identity/Path/To/Dir + +Targets: +- trunk/Identity/NewPath/To/Dir +- trunk/Translations/Identity/NewPath/To/Dir +- trunk/Scripts/Bash/Functions/Render/Config/Identity/NewPath/To/Dir + +Renderable layout 2: + +Command: +- centos-art render --copy=trunk/Identity/Themes/Motifs/TreeFlower \ + --to=trunk/Identity/Themes/Motifs/NewPath/To/Dir + +Sources: +- trunk/Identity/Themes/Motifs/TreeFlower +- trunk/Translations/Identity/Themes +- trunk/Translations/Identity/Themes/Motifs/TreeFlower +- trunk/Scripts/Bash/Functions/Render/Config/Identity/Themes +- trunk/Scripts/Bash/Functions/Render/Config/Identity/Themes/Motifs/TreeFlower + +Targets: +- trunk/Identity/Themes/Motifs/NewPath/To/Dir +- trunk/Translations/Identity/Themes +- trunk/Translations/Identity/Themes/Motifs/NewPath/To/Dir +- trunk/Scripts/Bash/Functions/Render/Config/Identity/Themes +- trunk/Scripts/Bash/Functions/Render/Config/Identity/Themes/Motifs/NewPath/To/Dir + +Notice that design models are not included in source or target +locations. This is intentional. In ``Renderable layout 2'', design +models live by their own, they just exist, they are there, available +for any artistic motif to use. By default `Themes/Models/Default' +design model directory structure is used, but other design models +directory structures (under Themes/Models/) can be created and used +changing the value of THEMEMODEL variable inside the pre-rendition +configuration script of the artistic motif source location you want to +produce. + +Notice how translations and pre-rendition configuration scripts may +both be equal in source and target. This is because such structures +are common to all artistic motifs (the default values to use when no +specific values are provided). + +- The common directory structures are not copied or deleted. We cannot + copy a directory structure to itself. + +- The common directory structures represent the default value to use + when no specific translations and/or pre-rendition configuration + script are provided inside source location. + +- The specific directory structures, if present, are both copiable and + removable. This is, when you perform a copy or delete action from + source, that source specific auxiliar directories are transfered in + the copy action to a new location (that specified by FLAG_TO + variable). + +- When translations and/or pre-rendition configuration scripts are + found inside the source directory structure, the centos-art.sh + script loads common auxiliar directories first and later specific + auxiliar directories. This way, identity rendition of source + locations can be customized idividually over the base of common + default values. + +- The specific auxiliar directories are optional. + +- The common auxiliar directories should be present always. This is, + in order to provide the information required by render functionality + (i.e., to make it functional in the more basic level of its + existence). + +Notice how the duplication process is done from `trunk/Identity' on, +not the oposite. If you try to duplicate a translation structure (or +similar auxiliar directory structures like pre-rendition configuration +scripts), the `trunk/Identity' for that translation is not created. +This limitation is impossed by the fact that many `trunk/Identity' +directory structures may reuse/share the same translation directory +structure. We cannot delete one translation (or similar) directory +structures while a related `trunk/Identity/' directory structure is +still in need of it. + +The `render_doCopy' functionality does duplicate directory structures +directly involved in rendition process only. Once such directories +have been duplicated, the functionality stops thereat. + +@subsection Usage + +@itemize +@item ... +@end itemize + +@subsection See also + +@menu +@comment --- Removed(* trunk Scripts Bash Functions Render Config::) --- +@end menu diff --git a/Manuals/Filesystem/trunk/Scripts/Bash/cli/Functions/Render/Config.texi b/Manuals/Filesystem/trunk/Scripts/Bash/cli/Functions/Render/Config.texi new file mode 100644 index 0000000..3b3322b --- /dev/null +++ b/Manuals/Filesystem/trunk/Scripts/Bash/cli/Functions/Render/Config.texi @@ -0,0 +1,192 @@ +@subsection Goals + +The @file{trunk/Scripts/Bash/Config} directory exists to oraganize +pre-rendering configuration scripts. + +@subsection Description + +Pre-rendering configuration scripts let you customize the way +@command{centos-art.sh} script renders identity and translation +repository entries. Pre-rendering configuration scripts are +@file{render.conf.sh} files with @command{render_loadConfig} function +definition inside. + +There is one @file{render.conf.sh} file for each pre-rendering +configuration entry. Pre-rendering configuration entries can be based +both on identity and translation repository entires. Pre-rendering +configuration entries are required for each identity entry, but not +for translation entries. + +@subsubsection The @file{render.conf.sh} identity model + +Inside CentOS Artwork Repository, we consider identity entries to all +directories under @file{trunk/Identity} directory. Identity entries can be +image-based or text-based. When you render image-based identity +entries you need to use image-based pre-rendering configuration +scripts. Likewise, when you render text-based identity entries you +need to use text-based pre-rendering configuration scripts. + +Inside identity pre-rendering configuration scripts, image-based +pre-rendering configuration scripts look like the following: + +@verbatim +#!/bin/bash + +function render_loadConfig { + + # Define rendering actions. + ACTIONS[0]='BASE:renderImage' + ACTIONS[1]='POST:renderFormats: tif xpm pdf ppm' + +} +@end verbatim + +Inside identity pre-rendering configuration scripts, text-based +pre-rendering configuration scripts look like the following: + +@verbatim +#!/bin/bash + +function render_loadConfig { + + # Define rendering actions. + ACTIONS[0]='BASE:renderText' + ACTIONS[1]='POST:formatText: --width=70 --uniform-spacing' + +} +@end verbatim + +When using identity pre-rendering configuration scripts, you can +extend both image-based and text-based pre-rendering configuration +scripts using image-based and text-based post-rendering actions, +respectively. + +@subsubsection The @file{render.conf.sh} translation model + +Translation pre-rendering configuration scripts take precedence before +default translation rendering action. Translation pre-rendering +actions are useful when default translation rendering action do not +fit itself to translation entry rendering requirements. + +@subsubsection The @file{render.conf.sh} rendering actions + +Inside both image-based and text-based identity pre-rendering +configuration scripts, we use the @samp{ACTIONS} array variable to +define the way @command{centos-art.sh} script performs identity +rendering. Identity rendering is organized by one @samp{BASE} action, +and optional @samp{POST} and @samp{LAST} rendering actions. + +The @samp{BASE} action specifies what kind of rendering does the +@command{centos-art.sh} script will perform with the files related to +the pre-rendering configuration script. The @samp{BASE} action is +required. Possible values to @samp{BASE} action are either +@samp{renderImage} or @samp{renderText} only. + +To specify the @samp{BASE} action you need to set the @samp{BASE:} +string followed by one of the possible values. For example, if you +want to render images, consider the following definition of +@samp{BASE} action: + +@verbatim +ACTIONS[0]='BASE:renderImage' +@end verbatim + +Only one @samp{BASE} action must be specified. If more than one +@samp{BASE} action is specified, the last one is used. If no +@samp{BASE} action is specified at all, an error is triggered and the +@command{centos-art.sh} script ends its execution. + +The @samp{POST} action specifies which action to apply for +each file rendered (at the rendering time). This action is optional. +You can set many different @samp{POST} actions to apply many different +actions over the same already rendered file. Possible values to +@samp{POST} action are @samp{renderFormats}, @samp{renderSyslinux}, +@samp{renderGrub}, etc. + +To specify the @samp{POST} action, you need to use set the +@samp{POST:} followed by the function name of the action you want to +perform. The exact form depends on your needs. For example, consider +the following example to produce @samp{xpm}, @samp{jpg}, and +@samp{tif} images, based on already rendered @samp{png} image, and +also organize the produced files in directories named as their own +extensions: + +@verbatim +ACTIONS[0]='BASE:renderImage' +ACTIONS[1]='POST:renderFormats: xpm jpg tif' +ACTIONS[2]='POST:groupByFormat: png xpm jpg tif' +@end verbatim + +In the previous example, file organization takes place at the moment +of rendering, just after producing the @samp{png} base file and before +going to the next file in the list of files to render. If you don't +want to organized the produced files in directories named as their own +extensions, just remove the @samp{POST:groupByFormat} action line: + +@verbatim +ACTIONS[0]='BASE:renderImage' +ACTIONS[1]='POST:renderFormats: xpm jpg tif' +@end verbatim + +The @samp{LAST} action specifies which actions to apply once the last +file in the list of files to process has been rendered. The +@samp{LAST} action is optional. Possible values for @samp{LAST} +actions may be @samp{groupByFormat}, @samp{renderGdmTgz}, etc. + +@quotation +@strong{Note} --- @strong{Removed}(xref:trunk Scripts Bash Functions Render) ---, to know more +about possible values for @samp{BASE}, @samp{POST} and @samp{LAST} +action definitions. +@end quotation + +To specify the @samp{LAST} action, you need to set the @samp{LAST:} +string followed by the function name of the action you want to +perform. For example, consider the following example if you want to +render all files first and organize them later: + +@verbatim +ACTIONS[0]='BASE:renderImage' +ACTIONS[1]='POST:renderFormats: xpm jpg tif' +ACTIONS[2]='LAST:groupByformat: png xpm jpg tif' +@end verbatim + +@subsection Usage + +Use the following commands to administer both identity and translation +pre-rendering configuration scripts: + +@table @samp + +@item centos-art config --create='path/to/dir/' + +Use this command to create @samp{path/to/dir} related pre-rendering +configuration script. + +@item centos-art config --edit='path/to/dir/' + +Use this command to edit @samp{path/to/dir} related pre-rendering +configuration script. + +@item centos-art config --read='path/to/dir/' + +Use this command to read @samp{path/to/dir} related pre-rendering +configuration script. + +@item centos-art config --remove='path/to/dir/' + +Use this command to remove @samp{path/to/dir} related pre-rendering +configuration script. + +@end table + +In the commands above, @samp{path/to/dir} refers to one renderable +directory path under @file{trunk/Identity} or +@file{trunk/Translations} structures only. + +@subsection See also + +@menu +* trunk Scripts Bash:: +@comment --- Removed(* trunk Scripts Bash Functions::) --- +@comment --- Removed(* trunk Scripts Bash Functions Render::) --- +@end menu diff --git a/Manuals/Filesystem/trunk/Scripts/Bash/cli/Functions/Shell.texi b/Manuals/Filesystem/trunk/Scripts/Bash/cli/Functions/Shell.texi new file mode 100644 index 0000000..a5016fe --- /dev/null +++ b/Manuals/Filesystem/trunk/Scripts/Bash/cli/Functions/Shell.texi @@ -0,0 +1,184 @@ +@subsection Goals + +This section exists to organize files related to @code{shell} +functionality of @file{centos-art.sh} script. + +@subsection Description + +The @code{shell} functionality of @file{centos-art.sh} script helps +you to maintain bash scripts inside repository. For example, suppose +you've created many functionalities for @file{centos-art.sh} script, +and you want to use a common copyright and license note for +consistency in all your script files. If you have a bunch of files, +doing this one by one wouldn't be a big deal. In contrast, if the +amount of files grows, updating the copyright and license note for all +of them would be a task rather tedious. The @code{shell} functionality +exists to solve maintainance tasks just as the one previously +mentioned. + +When you use @code{shell} functionality to update copyright inside +script files, it is required that your script files contain (at least) +the following top commentary structure: + +@float Figure,fig:trunk/Scripts/Bash/Functions/Shell:1 +@verbatim + 1| #!/bin/bash + 2| # + 3| # doSomething.sh -- The function description goes here. + 4| # + 5| # Copyright + 6| # + 7| # ... + 8| # + 9| # ---------------------------------------------------------------------- +10| # $Id$ +11| # ---------------------------------------------------------------------- +12| +13| function doSomething { +14| +15| } +@end verbatim +@caption{The functions script base comment structure} +@end float + +Relevant lines in the above structure are lines from 5 to 9. +Everything else in the file is left immutable. + +When you are updating copyright through @code{shell} +functionality, the @file{centos-art.sh} script replaces everything +in-between line 5 ---the first one matching @samp{^# Copyright .+$} +string--- and line 9---the first long dash separator matching @samp{^# +-+$}--- with the content of copyright template instance. + +@quotation +@strong{Caution} Be sure to add the long dash separator that matches +@samp{^# -+$} regular expression @emph{before} the function +definition. Otherwise, if the @samp{Copyright} line is present but no +long dash separator exists, @file{centos-art.sh} will remove anything +in-between the @samp{Copyright} line and the end of file. This way you +may lost your function definitions entirely. +@end quotation + +The copyright template instance is created from one copyright template +stored in the @file{Config/tpl_forCopyright.sed} file. The template +instance is created once, and later removed when no longer needed. At +this moment, when template instance is created, the +@file{centos-art.sh} script takes advantage of automation in order to +set copyright full name and date dynamically. + +When you use @code{shell} functionality to update copyright, the first +thing @file{shell} functionality does is requesting copyright +information to user, and later, if values were left empty (i.e., no +value was typed before pressing @key{RET} key), the @file{shell} +functionality uses its own default values. + +When @code{shell} functionality uses its own default values, the final +copyright note looks like the following: + +@float Figure,fig:trunk/Scripts/Bash/Functions/Shell:2 +@verbatim + 1| #!/bin/bash + 2| # + 3| # doSomthing.sh -- The function description goes here. + 4| # + 5| # Copyright (C) 2003, 2010 The CentOS Project + 6| # + 7| # This program is free software; you can redistribute it and/or modify + 8| # it under the terms of the GNU General Public License as published by + 9| # the Free Software Foundation; either version 2 of the License, or +10| # (at your option) any later version. +11| # +12| # This program is distributed in the hope that it will be useful, but +13| # WITHOUT ANY WARRANTY; without even the implied warranty of +14| # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +15| # General Public License for more details. +16| # +17| # You should have received a copy of the GNU General Public License +18| # along with this program; if not, write to the Free Software +19| # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 +20| # USA. +21| # +22| # ---------------------------------------------------------------------- +23| # $Id$ +24| # ---------------------------------------------------------------------- +25| +26| function doSomething { +27| +28| } +@end verbatim +@caption{The function script comment example} +@end float + +Relevant lines in the above structure are lines from 5 to 22. Pay +attention how the copyright line was built, and how the license was +added into the top comment where previously was just three dots. +Everything else in the file was left immutable. + +To change copyright information (i.e., full name or year information), +run the @code{shell} functionality over the root directory containing +the script files you want to update copyright in and enter the +appropriate information when it be requested. You can run the +@code{shell} functionality as many times as you need to. + +To change copyright license (i.e., the text in-between lines 7 and +20), you need to edit the @file{Config/tpl_forCopyright.sed} file, set +the appropriate information, and run the @code{shell} functionality +once again for changes to take effect over the files you specify. + +@quotation +@strong{Important} The @file{centos-art.sh} script is released as: + +@verbatim +GNU GENERAL PUBLIC LICENSE +Version 2, June 1991 + +Copyright (C) 1989, 1991 Free Software Foundation, Inc. +59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. +@end verbatim + +Do not change the license information under which @file{centos-art.sh} +script is released. Instead, if you think a different license must be +used, please share your reasons at @email{centos-devel@@centos-art.sh, +CentOS Developers mailing list}. +@end quotation + +@subsection Usage + +@table @command +@item centos-art sh --update-copyright='path/to/dir' +@itemx centos-art sh --update-copyright='path/to/dir' --filter='regex' +Use these commands to update copyright information in @samp{.sh} files +under @samp{path/to/dir} directory. +@end table + +When you provide @option{--filter='regex'} argument, the list of files +to process is reduced as specified in @samp{regex} regular expression. +Inside @file{centos-art.sh} script, the @samp{regex} regular +expression is used in combination with @command{find} command to look +for files matching the regular expression path pattern. + +@quotation +@strong{Warning} In order for @samp{regex} regular expression to match +a file, the @samp{regex} regular expresion must match the whole file +path not just the file name. +@end quotation + +For example, if you want to match all @file{render.conf.sh} files +inside @file{path/to/dir}, use the @code{.+/render.conf} regular +expression. Later, @file{centos-art.sh} script uses this value inside +@code{^$REGEX\.sh$} expression in order to build the final regular +expression (i.e., @code{^.+/render.conf\.sh$}) that is evaluated +against available file paths inside the list of files to process. + +Exceptionally, when you provide @option{--filter='regex'} in the way +that @samp{regex}, appended to @samp{path/to/dir/} (i.e. +@samp{path/to/dir/regex}), matches a regular file; the +@file{centos-art.sh} script uses the file matching as only file in the +list of files to process. + +@subsection See also + +@menu +* trunk Scripts Bash:: +@comment --- Removed(* trunk Scripts Bash Functions::) --- +@end menu diff --git a/Manuals/Filesystem/trunk/Scripts/Bash/cli/Functions/Svg.texi b/Manuals/Filesystem/trunk/Scripts/Bash/cli/Functions/Svg.texi new file mode 100644 index 0000000..341745d --- /dev/null +++ b/Manuals/Filesystem/trunk/Scripts/Bash/cli/Functions/Svg.texi @@ -0,0 +1,192 @@ +@subsection Goals + +This section exists to organize files related to @code{svg} +functionality of @file{centos-art.sh} script. + +@subsection Description + +The @code{svg} functionality of @file{centos-art.sh} script helps you +to maintain scalable vector graphics (SVG) inside repository. For +example, suppose you've been working in CentOS default design models +under @file{trunk/Identity/Themes/Models/}, and you want to set common +metadata to all of them, and later remove all unused SVG defintions +from @samp{*.svg} files. Doing so file by file may be a tedious task, +so the @file{centos-art.sh} script provides the @code{svg} +functionality to aid you maintain such actions. + +@cindex Metadata maintainance +@subsubsection Metadata maintainance + +The metadata used is defined by Inkscape 0.46 using the SVG standard +markup. The @file{centos-art.sh} script replaces everything +in-between @code{} tags with a +predefined metadata template we've set for this purpose. + +The metadata template was created using the metadata information of a +file which, using Inkscape 0.46, all metadata fields were set. This +created a complete markup representation of how SVG metadata would +look like. Later, we replaced every single static value with a +translation marker in the form @samp{=SOMETEXT=}, where +@code{SOMETEXT} is the name of its main opening tag. Later, we +transform the metadata template into a sed replacement set of commads +escaping new lines at the end of each line. + +With metadata template in place, the @file{centos-art.sh} script uses +it to create a metadata template instance for the file being processed +currently. The metadata template instance contains the metadata +portion of sed replacement commands with translation markers already +traduced. In this action, instance creation, is where we take +advantage of automation and generate metadata values like title, date, +keywords, source, identifier, and relation dynamically, based on the +file path @file{centos-art.sh} script is currently creating metadata +information for. + +With metadata template instance in place, the @file{centos-art.sh} +script uses it to replace real values inside all @samp{.svg} files +under the current location you're running the @file{centos-art.sh} +script on. Default behaviour is to ask user to enter each metadatum +required, one by one. If user leaves metadatum empty, by pressing +@key{RET} key, @file{centos-art.sh} uses its default value. + +The @file{centos-art.sh} script modifies the following metadata: + +@table @samp +@item Title +Name by which this document is formally known. If no value is set +here, @file{centos-art.sh} script uses the file name as title. + +@item Date +Date associated with the creation of this document (YYYY-MM-DD). If no +value is set here, @file{centos-art.sh} script uses the current date +information as in @command{date +%Y-%m-%d}. + +@item Creator +Name of entity primarily responsible for making the content of this +document. If no value is set here, @file{centos-art.sh} script uses +the string @samp{The CentOS Project}. + +@item Rights +Name of entity with rights to the intellectual Property of this +document. If no value is set here, @file{centos-art.sh} script uses +the string @samp{The CentOS Project}. + +@item Publisher +Name of entity responsible for making this document available. If no +value is set here, @file{centos-art.sh} script uses the string +@samp{The CentOS Project}. + +@item Identifier +Unique URI to reference this document. If no value is set here, +@file{centos-art.sh} script uses the current file path to build the +related url that points to current file location inside repository +central server. + +@item Source +Unique URI to reference the source of this document. If no value is +set here, @file{centos-art.sh} script uses current file path to build +the related url that points to current file location inside repository +central server. + +@item Relation +Unique URI to a related document. If no value is set here, +@file{centos-art.sh} script uses current file path to build the +related url that points to current file location inside repository +central server. + +@item Language +Two-letter language tag with optional subtags for the language of this +document. (e.g. @samp{en-GB}). If no value is set here, +@file{centos-art.sh} script uses the current locale information as in +@code{cli_getCurrentLocale} function. + +@item Keywords +The topic of this document as comma-separated key words, prhases, or +classifications. If no value is set here, @file{centos-art.sh} script +uses file path to build + +@item Coverage +Extent or scope of this document. If no value is set here, +@file{centos-art.sh} script uses the string @samp{The CentOS Project}. + +@item Description +Description about the document. If no value is set here, +@file{centos-art.sh} script uses uses empty value as default. + +@item Contributors +People that contributes in the creation/maintainance of the document. +If no value is set here, @file{centos-art.sh} script uses uses empty +value as default. +@end table + +The @samp{License} metadatum is not set as a choise, by now. It is +fixed @url{http://creativecommons.org/licenses/by-sa/3.0/, Creative +Common Attribution Share-Alike 3.0 License}. This is done in order to +grant license consistency among all SVG files we manage inside CentOS +Artwork Repository. + +@cindex Unused definitions +@subsubsection Unused definitions + +Many of the no-longer-used gradients, patterns, and markers (more +precisely, those which you edited manually) remain in the +corresponding palettes and can be reused for new objects. However if +you want to optimize your document, use the @samp{Vacuum Defs} command +in @samp{File} menu. It will remove any gradients, patterns, or +markers which are not used by anything in the document, making the +file smaller. + +If you have one or two couple of files, removing unused definitions +using the graphical interface may be enough to you. In contrast, if +you have dozens or even houndreds of scalable vector graphics files to +maintain it is not a fun task to use the graphical interface to remove +unused definitions editing those files one by one. + +To remove unused definitions from several scalable vector graphics +files, the @file{centos-art.sh} script uses Inkscape command-line +interface, specifically with the @option{--vaccum-defs} option. + +@subsection Usage + +@table @command +@item centos-art svg --update-metadata='path/to/dir' +@item centos-art svg --update-metadata='path/to/dir' --filter='regex' +Use these commands to update metadata information to @samp{.svg} files +under @samp{path/to/dir} directory. + +@item centos-art svg --vacuum-defs='path/to/dir' +@item centos-art svg --vacuum-defs='path/to/dir' --filter='regex' +Use these commands to remove unused definitions inside @samp{.svg} +files under @samp{path/to/dir} directory. +@end table + +When you provide @option{--filter='regex'} argument, the list of files +to process is reduced as specified in @samp{regex} regular expression. +Inside @file{centos-art.sh} script, the @samp{regex} regular +expression is used in combination with @command{find} command to look +for files matching the regular expression path pattern. + +@quotation +@strong{Warning} In order for @samp{regex} regular expression to match +a file, the @samp{regex} regular expresion must match the whole file +path not just the file name. +@end quotation + +For example, if you want to match all @file{summary.svg} files inside +@file{path/to/dir}, use the @code{.+/summary} regular expression. +Later, @file{centos-art.sh} script uses this value inside +@code{^$REGEX\.svg$} expression in order to build the final regular +expression (i.e., @code{^.+/summary\.svg$}) that is evaluated against +available file paths inside the list of files to process. + +Exceptionally, when you provide @option{--filter='regex'} in the way +that @samp{regex}, appended to @samp{path/to/dir/} (i.e. +@samp{path/to/dir/regex}), matches a regular file; the +@file{centos-art.sh} script uses the file matching as only file in the +list of files to process. + +@subsection See also + +@menu +* trunk Scripts Bash:: +@comment --- Removed(* trunk Scripts Bash Functions::) --- +@end menu diff --git a/Manuals/Filesystem/trunk/Scripts/Bash/cli/Functions/Verify.texi b/Manuals/Filesystem/trunk/Scripts/Bash/cli/Functions/Verify.texi new file mode 100644 index 0000000..ff98b51 --- /dev/null +++ b/Manuals/Filesystem/trunk/Scripts/Bash/cli/Functions/Verify.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 +* trunk Scripts Bash:: +@comment --- Removed(* trunk Scripts Bash Functions::) --- +@end menu diff --git a/Manuals/Filesystem/trunk/chapter-menu.texi b/Manuals/Filesystem/trunk/chapter-menu.texi index 00f41d9..a26cfb2 100644 --- a/Manuals/Filesystem/trunk/chapter-menu.texi +++ b/Manuals/Filesystem/trunk/chapter-menu.texi @@ -46,17 +46,17 @@ * trunk Manuals:: * trunk Scripts:: * trunk Scripts Bash:: -* trunk Scripts Bash centos-art:: -* trunk Scripts Bash centos-art Functions:: -* trunk Scripts Bash centos-art Functions Help:: -* trunk Scripts Bash centos-art Functions Html:: -* trunk Scripts Bash centos-art Functions Locale:: -* trunk Scripts Bash centos-art Functions Manual:: -* trunk Scripts Bash centos-art Functions Path:: -* trunk Scripts Bash centos-art Functions Render:: -* trunk Scripts Bash centos-art Functions Render Config:: -* trunk Scripts Bash centos-art Functions Shell:: -* trunk Scripts Bash centos-art Functions Svg:: -* trunk Scripts Bash centos-art Functions Verify:: +* trunk Scripts Bash cli:: +* trunk Scripts Bash cli Functions:: +* trunk Scripts Bash cli Functions Help:: +* trunk Scripts Bash cli Functions Html:: +* trunk Scripts Bash cli Functions Locale:: +* trunk Scripts Bash cli Functions Manual:: +* trunk Scripts Bash cli Functions Path:: +* trunk Scripts Bash cli Functions Render:: +* trunk Scripts Bash cli Functions Render Config:: +* trunk Scripts Bash cli Functions Shell:: +* trunk Scripts Bash cli Functions Svg:: +* trunk Scripts Bash cli Functions Verify:: * trunk Scripts Python:: @end menu diff --git a/Manuals/Filesystem/trunk/chapter-nodes.texi b/Manuals/Filesystem/trunk/chapter-nodes.texi index 06bbc0a..294a4cb 100644 --- a/Manuals/Filesystem/trunk/chapter-nodes.texi +++ b/Manuals/Filesystem/trunk/chapter-nodes.texi @@ -233,65 +233,65 @@ @cindex trunk Scripts Bash @include trunk/Scripts/Bash.texi -@node trunk Scripts Bash centos-art -@section trunk/Scripts/Bash/centos-art -@cindex trunk Scripts Bash centos-art -@include trunk/Scripts/Bash/centos-art.texi - -@node trunk Scripts Bash centos-art Functions -@section trunk/Scripts/Bash/centos-art/Functions -@cindex trunk Scripts Bash centos-art Functions -@include trunk/Scripts/Bash/centos-art/Functions.texi - -@node trunk Scripts Bash centos-art Functions Help -@section trunk/Scripts/Bash/centos-art/Functions/Help -@cindex trunk Scripts Bash centos-art Functions Help -@include trunk/Scripts/Bash/centos-art/Functions/Help.texi - -@node trunk Scripts Bash centos-art Functions Html -@section trunk/Scripts/Bash/centos-art/Functions/Html -@cindex trunk Scripts Bash centos-art Functions Html -@include trunk/Scripts/Bash/centos-art/Functions/Html.texi - -@node trunk Scripts Bash centos-art Functions Locale -@section trunk/Scripts/Bash/centos-art/Functions/Locale -@cindex trunk Scripts Bash centos-art Functions Locale -@include trunk/Scripts/Bash/centos-art/Functions/Locale.texi - -@node trunk Scripts Bash centos-art Functions Manual -@section trunk/Scripts/Bash/centos-art/Functions/Manual -@cindex trunk Scripts Bash centos-art Functions Manual -@include trunk/Scripts/Bash/centos-art/Functions/Manual.texi - -@node trunk Scripts Bash centos-art Functions Path -@section trunk/Scripts/Bash/centos-art/Functions/Path -@cindex trunk Scripts Bash centos-art Functions Path -@include trunk/Scripts/Bash/centos-art/Functions/Path.texi - -@node trunk Scripts Bash centos-art Functions Render -@section trunk/Scripts/Bash/centos-art/Functions/Render -@cindex trunk Scripts Bash centos-art Functions Render -@include trunk/Scripts/Bash/centos-art/Functions/Render.texi - -@node trunk Scripts Bash centos-art Functions Render Config -@section trunk/Scripts/Bash/centos-art/Functions/Render/Config -@cindex trunk Scripts Bash centos-art Functions Render Config -@include trunk/Scripts/Bash/centos-art/Functions/Render/Config.texi - -@node trunk Scripts Bash centos-art Functions Shell -@section trunk/Scripts/Bash/centos-art/Functions/Shell -@cindex trunk Scripts Bash centos-art Functions Shell -@include trunk/Scripts/Bash/centos-art/Functions/Shell.texi - -@node trunk Scripts Bash centos-art Functions Svg -@section trunk/Scripts/Bash/centos-art/Functions/Svg -@cindex trunk Scripts Bash centos-art Functions Svg -@include trunk/Scripts/Bash/centos-art/Functions/Svg.texi - -@node trunk Scripts Bash centos-art Functions Verify -@section trunk/Scripts/Bash/centos-art/Functions/Verify -@cindex trunk Scripts Bash centos-art Functions Verify -@include trunk/Scripts/Bash/centos-art/Functions/Verify.texi +@node trunk Scripts Bash cli +@section trunk/Scripts/Bash/cli +@cindex trunk Scripts Bash cli +@include trunk/Scripts/Bash/cli.texi + +@node trunk Scripts Bash cli Functions +@section trunk/Scripts/Bash/cli/Functions +@cindex trunk Scripts Bash cli Functions +@include trunk/Scripts/Bash/cli/Functions.texi + +@node trunk Scripts Bash cli Functions Help +@section trunk/Scripts/Bash/cli/Functions/Help +@cindex trunk Scripts Bash cli Functions Help +@include trunk/Scripts/Bash/cli/Functions/Help.texi + +@node trunk Scripts Bash cli Functions Html +@section trunk/Scripts/Bash/cli/Functions/Html +@cindex trunk Scripts Bash cli Functions Html +@include trunk/Scripts/Bash/cli/Functions/Html.texi + +@node trunk Scripts Bash cli Functions Locale +@section trunk/Scripts/Bash/cli/Functions/Locale +@cindex trunk Scripts Bash cli Functions Locale +@include trunk/Scripts/Bash/cli/Functions/Locale.texi + +@node trunk Scripts Bash cli Functions Manual +@section trunk/Scripts/Bash/cli/Functions/Manual +@cindex trunk Scripts Bash cli Functions Manual +@include trunk/Scripts/Bash/cli/Functions/Manual.texi + +@node trunk Scripts Bash cli Functions Path +@section trunk/Scripts/Bash/cli/Functions/Path +@cindex trunk Scripts Bash cli Functions Path +@include trunk/Scripts/Bash/cli/Functions/Path.texi + +@node trunk Scripts Bash cli Functions Render +@section trunk/Scripts/Bash/cli/Functions/Render +@cindex trunk Scripts Bash cli Functions Render +@include trunk/Scripts/Bash/cli/Functions/Render.texi + +@node trunk Scripts Bash cli Functions Render Config +@section trunk/Scripts/Bash/cli/Functions/Render/Config +@cindex trunk Scripts Bash cli Functions Render Config +@include trunk/Scripts/Bash/cli/Functions/Render/Config.texi + +@node trunk Scripts Bash cli Functions Shell +@section trunk/Scripts/Bash/cli/Functions/Shell +@cindex trunk Scripts Bash cli Functions Shell +@include trunk/Scripts/Bash/cli/Functions/Shell.texi + +@node trunk Scripts Bash cli Functions Svg +@section trunk/Scripts/Bash/cli/Functions/Svg +@cindex trunk Scripts Bash cli Functions Svg +@include trunk/Scripts/Bash/cli/Functions/Svg.texi + +@node trunk Scripts Bash cli Functions Verify +@section trunk/Scripts/Bash/cli/Functions/Verify +@cindex trunk Scripts Bash cli Functions Verify +@include trunk/Scripts/Bash/cli/Functions/Verify.texi @node trunk Scripts Python @section trunk/Scripts/Python