% Part   : Concepts

% Chapter: Scripts

% ------------------------------------------------------------

% $Id: scripts.tex 6207 2010-08-05 13:11:13Z al $

% ------------------------------------------------------------

\begin{description}

\item[framework:] trunk/Scripts/

\end{description}

\noindent Inside CentOS Artwork Repository, scripts are organized in

three groups: ``invocation scripts'', ``configuration scripts'' and

``function scripts''. Scripts are mainly used to help you automate and

standardize tasks. A graphical representation of how scripts are

organized inside CentOS Artwork Repository is illustrated in

\autoref{fig:Concepts:Scripts}.

\begin{figure}[!hbp]

\centering

\includegraphics[width=0.8\textwidth]{%

   ../Identity/Models/Img/en/Scripts/initFunctions.pdf}

\caption{The scripts organization model.%

   \label{fig:Concepts:Scripts}}

\end{figure}

\section{Invocation Scripts}

\hypertarget{sec:Concepts:Scripts:Invocation}{}

\label{sec:Concepts:Scripts:Invocation}

Invocation scripts are identified by the name \texttt{render.sh}. You

may find invocation scripts inside \texttt{trunk/Translations/} and

\texttt{trunk/Identity/} structures.  Invocation scripts' main purpose

is calling the appropriate configuration script.

\section{Configuration Scripts}

\hypertarget{sec:Concepts:Scripts:Configuration}{}

\label{sec:Concepts:Scripts:Configuration}

\begin{description}

\item[framework:] trunk/Scripts/Config/

\end{description}

\noindent Configuration scripts are identified by the name

\texttt{render.conf.sh}. In the script organization model

(\autoref{fig:Concepts:Scripts}), configuration scripts are the first

scripts executed by you after running the invocation script

(\texttt{render.sh}).  Generally, configuration scripts are short

files that initialize functions, set variable definitions, and call

the appropriate function to start rendering.

\subsection{Initialize Functions}

Function initialization is the first action you do inside

configuration scripts.  By default, functions are initialized using

the \texttt{initFunctions.sh} script, as illustrated in

\autoref{fig:Concepts:Scripts:Configuration:initFunctions}.  The

\texttt{initFunctions.sh} script looks for functions definitions in

files that match the expansion \texttt{*.sh} inside the

\texttt{trunk/Scripts/Functions/} path, and exports them to the

current shell environment, that created when you ran the invocation

script.

\begin{figure}[!hbp]

\hrulefill

\begin{verbatim}

# Initialize functions.

. /home/centos/artwork/trunk/Scripts/initFunctions.sh

\end{verbatim}

\hrulefill

\caption{Function initialization inside configuration scripts.%

   \label{fig:Concepts:Scripts:Configuration:initFunctions}}

\end{figure}

Once functions are initialized, they are ready to be used by you, in

any point after its initialization.  This initialization arms you with

a customizable set of functionalities that can be used on

configuration scripts and reused inside functions themselves.

\subsection{Define Artwork Component}

The \texttt{ARTCOMP} variable defines the artwork component you want

to render.  The \texttt{ARTCOMP}'s value defines the specific artwork

component's matching list and Themes' translation path.  The

\texttt{ARTCOMP}'s value is built using the translation path structure

as reference.  For example, if you want to render Anaconda progress

files, you need to know that artwork component's translation path

which is:\\

\\

\fbox{trunk/Translations/Identity/Themes/Distro/Anaconda/Progress}\\

\\

and then, go to its \texttt{render.conf.sh} file to define

\texttt{ARTCOMP} as the following:\\

\\

\fbox{ARTCOMP='Distro/Anaconda/Progress'}\\

\\

The \texttt{ARTCOMP}'s value is processed by \texttt{getMatchingList}

function to determine the specific artwork component's

translation-design matching list. The matching list function is

described in \autoref{sec:Concepts:Scripts:Function:getMatchingList}.

\subsection{Define Filtering Pattern}

The \texttt{REGEX} variable defines a regular expression as filtering

pattern.  If the filtering pattern is specified, the rendering process

is limited to the amount of files matching the filtering pattern.  By

default, this value is set to receive the shell's first argument

(\texttt{\$1}).  This let you pass the filtering pattern on the

command line, at rendering time.  If you need a fixed value for the

filtering pattern, you can change the \texttt{REGEX}'s value on your

working copy to whatever you need, but please do no commit that.

\begin{figure}[!hbp]

\hrulefill

\begin{verbatim}

# Define filtering pattern. This is a regular expression 

# matching the translation path.

REGEX="$1"

\end{verbatim}

\hrulefill

\caption{Define filtering pattern inside configuration scripts.%

   \label{fig:Concepts:Scripts:Configuration:REGEX}}

\end{figure}

\subsection{Define Post-rendering Actions}

\hypertarget{sec:Concepts:Scripts:Configuration:ACTIONS}{}

\label{sec:Concepts:Scripts:Configuration:ACTIONS}

Post-rendering actions are specific functionalities applied to the

final files produced by base rendering functions like

\texttt{renderImage} and \texttt{renderText}.  Post-rendering actions

are defined by the \texttt{ACTIONS} array variable.  By default, the

\texttt{ACTIONS}'s value is set to empty (\texttt{ACTIONS[0]=''})

which provokes no post-rendering action to be applied. A different

configuration is illustrated on

\autoref{fig:Concepts:Scripts:Configuration:ACTIONS}. 

When rendering images, using \texttt{renderImage}, the only result you

get is in PNG format. This is enough most of the time. But in some

other situations, you need to produce the same image in many different

formats (i.e. xpm, pdf, tiff, xbm, etc.). These tasks are very

specific and are not included inside \texttt{renderImage} function.

Instead, the \texttt{renderFormats} function was created and used as

post-rendering action in these situations.

When rendering texts, using \texttt{renderText}, the only result you

get is in plain text format. Again, this is enough most of the time.

But in some other situations, you need to modify the final result to

provide some standardizations like: maximum line width, indentation of

first line different from second, one space between words, two after

sentences, etc. These tasks are very specific and are not included

inside \texttt{renderText} function. Instead, the \texttt{formatText}

function was created and used as post-rendering action in these

situations.

\begin{figure}[!hbp]

\hrulefill

\begin{verbatim}

# Define post-rendering actions. An empty value means that no

# post-rendering action is applied.

ACTIONS[0]='renderFormats: tif xpm pdf ppm'

ACTIONS[1]='groupByFormat: png tif xpm pdf ppm'

\end{verbatim}

\hrulefill

\caption[Define post-rendering actions.]{Define post-rendering\

actions. In this figure, post-rendering actions are used to produce\

tif, xpm, pdf, ppm, image formats (from the base PNG image format)\

and group them (PNG format included) inside directories. This is, all\

png files are stored inside a png directory, all xpm files are\

stored inside a xpm directory, and so on.%

   \label{fig:Concepts:Scripts:Configuration:ACTIONS}}

\end{figure}

\subsection{Start Rendering}

The start rendering section defines the base action to do when the

current configuration script is called. In this section what you do is

calling one of the following functions: \texttt{renderImage}

(\autoref{sec:Concepts:Scripts:Function:renderImage}), or

\texttt{renderText}

(\autoref{sec:Concepts:Scripts:Function:renderText}).

\section{Function Scripts}

\hypertarget{sec:Concepts:Scripts:Function}{}

\label{sec:Concepts:Scripts:Function}

\begin{description}

\item[framework:] trunk/Scripts/Functions/

\end{description}

\noindent Function scripts are, in fact, shell functions.  A shell

function stores a series of commands for later execution.  When the

name of a shell function is used as a simple command name, the list of

commands associated with that function name is executed.  Functions

are executed in the context of the current shell; no new process is

created to interpret them (contrast this with the execution  of a

shell script).

\subsection{renderImage}

\hypertarget{sec:Concepts:Scripts:Function:renderImage}{}

\label{sec:Concepts:Scripts:Function:renderImage}

Inside CentOS Artwork Repository, the \texttt{renderImage} function is

the heart of image production. The \texttt{renderImage} function takes

translation files and apply them to design templates, as specified in

the artwork componet's matching list that is been rendered. The final

result are PNG images based on design templates and translation files.

Additionally, the \texttt{renderImage} function accepts the following

post-rendering actions:

\begin{description}

\item[renderFormats:] The \texttt{renderFormats} function let you

produce different image formats from the base PNG image format.  The

amount of image formats you can produce with \texttt{renderFormats} is

limited to the amount of image formats that ImageMagick command line

image manipulation tool can support.

\item[groupByFormat:] The \texttt{renderByFormat} function let you

group similar image formats inside common directories.

\item[renderGrub:] The \texttt{renderGrub} function let you produce 14

colors images from the base PNG image format. The \texttt{renderGrub}

function is used to automate GRUB artwork component image production.

For this function to work, it is required to define the

\texttt{grub.ppm} palette first.

\item[renderSyslinux:] The \texttt{renderSyslinux} function let you

produce LSS16 images from the base PNG image format. The

\texttt{renderSyslinux} function is used to automate Anaconda prompt

artwork component image production.  For this function to work, it is

required to define the \texttt{syslinux.ppm} and \texttt{syslinux.hex}

palettes first.

\item[renderBrands:] The \texttt{renderBrands} function let you

produce different image formats from the base PNG image format.

Basically, it is does the same of \texttt{renderFormats}, plus two

colors grayscale, and emboss effect convertions that are not included

inside \texttt{renderFormats}.

\end{description}

\subsection{renderText}

\hypertarget{sec:Concepts:Scripts:Function:renderText}{}

\label{sec:Concepts:Scripts:Function:renderText}

The \texttt{renderText} function produce plain text files from text

plain design tempaltes and translation files. The \texttt{renderText}

standardize the text rendering process inside CentOS Artwork

Repository. Additionally, the \texttt{renderText} function accepts the

following post-rendering actions:

\begin{description}

\item[formatText:] The \texttt{formatText} function, let you format

plain text files. This function uses the GNU's \texttt{fmt} tool as

base to do all modifications.

\end{description}

\subsection{getMatchingList}

\hypertarget{sec:Concepts:Scripts:Function:getMatchingList}{}

\label{sec:Concepts:Scripts:Function:getMatchingList}

The matching list specifies the relation between design templates and

translation files that artwork components have. The

\texttt{renderImage} and \texttt{renderText} functions require this

information in order to work properly. 

Initially, the matching list was defined explicitly and independently

inside each artwork component's configuration script. Later, as many

of these components had just the same configuration stuff, the code

was reduced and unified inside \texttt{getMatchingList} function.

Inside \texttt{getMatchingList}, there is a case selection statement

where specific matching lists cases are defined, and one default

behaivour that match in thoses cases where none else does.  

The matching list code reduction changed the way you customize artwork

component's matching list.  From now on, you look inside configuration

files to be sure that \texttt{ARTCOMP} variable refers to the

appropriate artwork component, and inside \texttt{getMatchingList}

function to define its matching list.  For example, when rendering

Anaconda progress, its matching list specifies which translation files

apply which design templates. So, to change the matching list of this

artwork component, you need to edit the function

\texttt{getMatchingList} and set the appropriate relation there, in

the Anaconda progress matching list specification.

When setting artwork components' matching list, you can use any of the

following configuration available:

\begin{description}

\item[Configuration 1:] Specific translation files are applied to

specific design templates. In this configuration you have detailed

control over which translation files are applied to which design

template.

\begin{verbatim}

MATCHINGLIST="\

design-template-A.svg: translation-file-1.sed translation-file-2.sed

design-template-B.svg: translation-file-3.sed translation-file-4.sed

"

\end{verbatim}

Another way to write the previous example is: 

\begin{verbatim}

MATCHINGLIST="\

design-template-A.svg:\

   translation-file-1.sed\

   translation-file-2.sed

design-template-B.svg:\

   translation-file-3.sed\

   translation-file-4.sed

"

\end{verbatim}

In the above examples translation files 1 and 2 apply

design-template-A.svg. Likewise, translation files 3 and 4 apply

design-template-B.svg. That was a simple case, but what about if you

have hundreds of translation files to apply to specific design

templates? Lets say, translation files from 1 to 49 apply

design-template-A.svg and translation files from 50 to 99 apply

design-template-B.svg.  It would be tiresome to write down the name of

every single file in the above configuration. In these situations you

can ``generate'' the translation files as shown below: 

\begin{verbatim}

MATCHINGLIST="\

design-template-A.svg:\

   $(for NUMBER in $(sed 1 49);do

      echo -n translation-file-${NUMBER}.sed ' '

     done)

design-template-B.svg:\

   $(for NUMBER in $(sed 50 99);do

      echo -n translation-file-${NUMBER}.sed ' '

     done)

"

\end{verbatim}

Another interesting case is when you need to apply hundreds of

translation files to hundreds of design templates, in a file structure

where they both share a common bond path.  That is the

\texttt{Identity/Brands} artwork component case.  Writing down such a

matching list consumes lot of time.  So you can ``generate'' the

entire matching list like the following:

\begin{verbatim}

MATCHINGLIST="\

$(for TEMPLATE in $(find $(getPath 'trunk/Identity/Brands')/tpl \

   -name '*.svg' | sed -r 's!.*/Brands/Tpl/(.*)$!\1!' | sort );do

   TRANSLATION=$(find $(getPath \

      'trunk/Translations/Identity/Brands')/$(echo $TEMPLATE \

      | sed 's!\.svg!!') -name '*.sed' \

      | sed -r 's!^.*/Brands/(.*)$!\1!' \

      | sort | tr '\n' ' ')

   echo $TEMPLATE: $TRANSLATION

   done)

"

\end{verbatim}

\item[Configuration 2:] All translation files are applied to a single

design template.  In this configuration all artwork component's

translation files are applied to one design template

(design-template-A.svg for the matter of this case).

\begin{verbatim}

MATCHINGLIST="design-template-A.svg"

\end{verbatim}

\item[Configuration 3:] Translation files are applied to design

templates that share a common name. In this configuration translation

files are applied to design templates taking the name part, without

extension, as reference.  This means that, if you have a translation

file named \texttt{File-1.sed} you need to have a \texttt{File-1.svg}

inside design templates. This way, \texttt{File-1.sed} can be applied

to \texttt{File-1.svg} and, as result, produce the \texttt{File-1.png}

file.  This is the default matching list behaivour.

\begin{verbatim}

MATCHINGLIST=""

\end{verbatim}

\end{description}

\subsection{getPath}

The \texttt{getPath} function creates the artwork component's absolute

path. Before output the absolute path, \texttt{getPath} removes any

``strange'' character from the final path. For \texttt{getPath} to

work, the relative path to the artwork component should be provided

from \texttt{trunk/}'s directory level on.