Blame Manual/repository-latex/Concepts/scripts.tex

4c79b5
% Part   : Concepts
4c79b5
% Chapter: Scripts
4c79b5
% ------------------------------------------------------------
4c79b5
% $Id: scripts.tex 6207 2010-08-05 13:11:13Z al $
4c79b5
% ------------------------------------------------------------
4c79b5
4c79b5
\begin{description}
4c79b5
\item[framework:] trunk/Scripts/
4c79b5
\end{description}
4c79b5
4c79b5
\noindent Inside CentOS Artwork Repository, scripts are organized in
4c79b5
three groups: ``invocation scripts'', ``configuration scripts'' and
4c79b5
``function scripts''. Scripts are mainly used to help you automate and
4c79b5
standardize tasks. A graphical representation of how scripts are
4c79b5
organized inside CentOS Artwork Repository is illustrated in
4c79b5
\autoref{fig:Concepts:Scripts}.
4c79b5
4c79b5
\begin{figure}[!hbp]
4c79b5
\centering
4c79b5
\includegraphics[width=0.8\textwidth]{%
4c79b5
   ../Identity/Models/Img/en/Scripts/initFunctions.pdf}
4c79b5
\caption{The scripts organization model.%
4c79b5
   \label{fig:Concepts:Scripts}}
4c79b5
\end{figure}
4c79b5
4c79b5
\section{Invocation Scripts}
4c79b5
\hypertarget{sec:Concepts:Scripts:Invocation}{}
4c79b5
\label{sec:Concepts:Scripts:Invocation}
4c79b5
4c79b5
Invocation scripts are identified by the name \texttt{render.sh}. You
4c79b5
may find invocation scripts inside \texttt{trunk/Translations/} and
4c79b5
\texttt{trunk/Identity/} structures.  Invocation scripts' main purpose
4c79b5
is calling the appropriate configuration script.
4c79b5
4c79b5
\section{Configuration Scripts}
4c79b5
\hypertarget{sec:Concepts:Scripts:Configuration}{}
4c79b5
\label{sec:Concepts:Scripts:Configuration}
4c79b5
4c79b5
\begin{description}
4c79b5
\item[framework:] trunk/Scripts/Config/
4c79b5
\end{description}
4c79b5
4c79b5
\noindent Configuration scripts are identified by the name
4c79b5
\texttt{render.conf.sh}. In the script organization model
4c79b5
(\autoref{fig:Concepts:Scripts}), configuration scripts are the first
4c79b5
scripts executed by you after running the invocation script
4c79b5
(\texttt{render.sh}).  Generally, configuration scripts are short
4c79b5
files that initialize functions, set variable definitions, and call
4c79b5
the appropriate function to start rendering.
4c79b5
4c79b5
\subsection{Initialize Functions}
4c79b5
4c79b5
Function initialization is the first action you do inside
4c79b5
configuration scripts.  By default, functions are initialized using
4c79b5
the \texttt{initFunctions.sh} script, as illustrated in
4c79b5
\autoref{fig:Concepts:Scripts:Configuration:initFunctions}.  The
4c79b5
\texttt{initFunctions.sh} script looks for functions definitions in
4c79b5
files that match the expansion \texttt{*.sh} inside the
4c79b5
\texttt{trunk/Scripts/Functions/} path, and exports them to the
4c79b5
current shell environment, that created when you ran the invocation
4c79b5
script.
4c79b5
4c79b5
\begin{figure}[!hbp]
4c79b5
\hrulefill
4c79b5
\begin{verbatim}
4c79b5
# Initialize functions.
4c79b5
. /home/centos/artwork/trunk/Scripts/initFunctions.sh
4c79b5
\end{verbatim}
4c79b5
\hrulefill
4c79b5
\caption{Function initialization inside configuration scripts.%
4c79b5
   \label{fig:Concepts:Scripts:Configuration:initFunctions}}
4c79b5
\end{figure}
4c79b5
4c79b5
Once functions are initialized, they are ready to be used by you, in
4c79b5
any point after its initialization.  This initialization arms you with
4c79b5
a customizable set of functionalities that can be used on
4c79b5
configuration scripts and reused inside functions themselves.
4c79b5
4c79b5
\subsection{Define Artwork Component}
4c79b5
4c79b5
The \texttt{ARTCOMP} variable defines the artwork component you want
4c79b5
to render.  The \texttt{ARTCOMP}'s value defines the specific artwork
4c79b5
component's matching list and Themes' translation path.  The
4c79b5
\texttt{ARTCOMP}'s value is built using the translation path structure
4c79b5
as reference.  For example, if you want to render Anaconda progress
4c79b5
files, you need to know that artwork component's translation path
4c79b5
which is:\\
4c79b5
\\
4c79b5
\fbox{trunk/Translations/Identity/Themes/Distro/Anaconda/Progress}\\
4c79b5
\\
4c79b5
and then, go to its \texttt{render.conf.sh} file to define
4c79b5
\texttt{ARTCOMP} as the following:\\
4c79b5
\\
4c79b5
\fbox{ARTCOMP='Distro/Anaconda/Progress'}\\
4c79b5
\\
4c79b5
The \texttt{ARTCOMP}'s value is processed by \texttt{getMatchingList}
4c79b5
function to determine the specific artwork component's
4c79b5
translation-design matching list. The matching list function is
4c79b5
described in \autoref{sec:Concepts:Scripts:Function:getMatchingList}.
4c79b5
4c79b5
\subsection{Define Filtering Pattern}
4c79b5
4c79b5
The \texttt{REGEX} variable defines a regular expression as filtering
4c79b5
pattern.  If the filtering pattern is specified, the rendering process
4c79b5
is limited to the amount of files matching the filtering pattern.  By
4c79b5
default, this value is set to receive the shell's first argument
4c79b5
(\texttt{\$1}).  This let you pass the filtering pattern on the
4c79b5
command line, at rendering time.  If you need a fixed value for the
4c79b5
filtering pattern, you can change the \texttt{REGEX}'s value on your
4c79b5
working copy to whatever you need, but please do no commit that.
4c79b5
4c79b5
\begin{figure}[!hbp]
4c79b5
\hrulefill
4c79b5
\begin{verbatim}
4c79b5
# Define filtering pattern. This is a regular expression 
4c79b5
# matching the translation path.
4c79b5
REGEX="$1"
4c79b5
\end{verbatim}
4c79b5
\hrulefill
4c79b5
\caption{Define filtering pattern inside configuration scripts.%
4c79b5
   \label{fig:Concepts:Scripts:Configuration:REGEX}}
4c79b5
\end{figure}
4c79b5
4c79b5
\subsection{Define Post-rendering Actions}
4c79b5
\hypertarget{sec:Concepts:Scripts:Configuration:ACTIONS}{}
4c79b5
\label{sec:Concepts:Scripts:Configuration:ACTIONS}
4c79b5
4c79b5
Post-rendering actions are specific functionalities applied to the
4c79b5
final files produced by base rendering functions like
4c79b5
\texttt{renderImage} and \texttt{renderText}.  Post-rendering actions
4c79b5
are defined by the \texttt{ACTIONS} array variable.  By default, the
4c79b5
\texttt{ACTIONS}'s value is set to empty (\texttt{ACTIONS[0]=''})
4c79b5
which provokes no post-rendering action to be applied. A different
4c79b5
configuration is illustrated on
4c79b5
\autoref{fig:Concepts:Scripts:Configuration:ACTIONS}. 
4c79b5
4c79b5
When rendering images, using \texttt{renderImage}, the only result you
4c79b5
get is in PNG format. This is enough most of the time. But in some
4c79b5
other situations, you need to produce the same image in many different
4c79b5
formats (i.e. xpm, pdf, tiff, xbm, etc.). These tasks are very
4c79b5
specific and are not included inside \texttt{renderImage} function.
4c79b5
Instead, the \texttt{renderFormats} function was created and used as
4c79b5
post-rendering action in these situations.
4c79b5
4c79b5
When rendering texts, using \texttt{renderText}, the only result you
4c79b5
get is in plain text format. Again, this is enough most of the time.
4c79b5
But in some other situations, you need to modify the final result to
4c79b5
provide some standardizations like: maximum line width, indentation of
4c79b5
first line different from second, one space between words, two after
4c79b5
sentences, etc. These tasks are very specific and are not included
4c79b5
inside \texttt{renderText} function. Instead, the \texttt{formatText}
4c79b5
function was created and used as post-rendering action in these
4c79b5
situations.
4c79b5
4c79b5
\begin{figure}[!hbp]
4c79b5
\hrulefill
4c79b5
\begin{verbatim}
4c79b5
# Define post-rendering actions. An empty value means that no
4c79b5
# post-rendering action is applied.
4c79b5
ACTIONS[0]='renderFormats: tif xpm pdf ppm'
4c79b5
ACTIONS[1]='groupByFormat: png tif xpm pdf ppm'
4c79b5
\end{verbatim}
4c79b5
\hrulefill
4c79b5
\caption[Define post-rendering actions.]{Define post-rendering\
4c79b5
actions. In this figure, post-rendering actions are used to produce\
4c79b5
tif, xpm, pdf, ppm, image formats (from the base PNG image format)\
4c79b5
and group them (PNG format included) inside directories. This is, all\
4c79b5
png files are stored inside a png directory, all xpm files are\
4c79b5
stored inside a xpm directory, and so on.%
4c79b5
   \label{fig:Concepts:Scripts:Configuration:ACTIONS}}
4c79b5
\end{figure}
4c79b5
4c79b5
\subsection{Start Rendering}
4c79b5
4c79b5
The start rendering section defines the base action to do when the
4c79b5
current configuration script is called. In this section what you do is
4c79b5
calling one of the following functions: \texttt{renderImage}
4c79b5
(\autoref{sec:Concepts:Scripts:Function:renderImage}), or
4c79b5
\texttt{renderText}
4c79b5
(\autoref{sec:Concepts:Scripts:Function:renderText}).
4c79b5
4c79b5
\section{Function Scripts}
4c79b5
\hypertarget{sec:Concepts:Scripts:Function}{}
4c79b5
\label{sec:Concepts:Scripts:Function}
4c79b5
4c79b5
\begin{description}
4c79b5
\item[framework:] trunk/Scripts/Functions/
4c79b5
\end{description}
4c79b5
4c79b5
\noindent Function scripts are, in fact, shell functions.  A shell
4c79b5
function stores a series of commands for later execution.  When the
4c79b5
name of a shell function is used as a simple command name, the list of
4c79b5
commands associated with that function name is executed.  Functions
4c79b5
are executed in the context of the current shell; no new process is
4c79b5
created to interpret them (contrast this with the execution  of a
4c79b5
shell script).
4c79b5
4c79b5
\subsection{renderImage}
4c79b5
\hypertarget{sec:Concepts:Scripts:Function:renderImage}{}
4c79b5
\label{sec:Concepts:Scripts:Function:renderImage}
4c79b5
4c79b5
Inside CentOS Artwork Repository, the \texttt{renderImage} function is
4c79b5
the heart of image production. The \texttt{renderImage} function takes
4c79b5
translation files and apply them to design templates, as specified in
4c79b5
the artwork componet's matching list that is been rendered. The final
4c79b5
result are PNG images based on design templates and translation files.
4c79b5
4c79b5
Additionally, the \texttt{renderImage} function accepts the following
4c79b5
post-rendering actions:
4c79b5
4c79b5
\begin{description}
4c79b5
4c79b5
\item[renderFormats:] The \texttt{renderFormats} function let you
4c79b5
produce different image formats from the base PNG image format.  The
4c79b5
amount of image formats you can produce with \texttt{renderFormats} is
4c79b5
limited to the amount of image formats that ImageMagick command line
4c79b5
image manipulation tool can support.
4c79b5
4c79b5
\item[groupByFormat:] The \texttt{renderByFormat} function let you
4c79b5
group similar image formats inside common directories.
4c79b5
4c79b5
\item[renderGrub:] The \texttt{renderGrub} function let you produce 14
4c79b5
colors images from the base PNG image format. The \texttt{renderGrub}
4c79b5
function is used to automate GRUB artwork component image production.
4c79b5
For this function to work, it is required to define the
4c79b5
\texttt{grub.ppm} palette first.
4c79b5
4c79b5
\item[renderSyslinux:] The \texttt{renderSyslinux} function let you
4c79b5
produce LSS16 images from the base PNG image format. The
4c79b5
\texttt{renderSyslinux} function is used to automate Anaconda prompt
4c79b5
artwork component image production.  For this function to work, it is
4c79b5
required to define the \texttt{syslinux.ppm} and \texttt{syslinux.hex}
4c79b5
palettes first.
4c79b5
4c79b5
\item[renderBrands:] The \texttt{renderBrands} function let you
4c79b5
produce different image formats from the base PNG image format.
4c79b5
Basically, it is does the same of \texttt{renderFormats}, plus two
4c79b5
colors grayscale, and emboss effect convertions that are not included
4c79b5
inside \texttt{renderFormats}.
4c79b5
4c79b5
\end{description}
4c79b5
4c79b5
\subsection{renderText}
4c79b5
\hypertarget{sec:Concepts:Scripts:Function:renderText}{}
4c79b5
\label{sec:Concepts:Scripts:Function:renderText}
4c79b5
4c79b5
The \texttt{renderText} function produce plain text files from text
4c79b5
plain design tempaltes and translation files. The \texttt{renderText}
4c79b5
standardize the text rendering process inside CentOS Artwork
4c79b5
Repository. Additionally, the \texttt{renderText} function accepts the
4c79b5
following post-rendering actions:
4c79b5
4c79b5
\begin{description}
4c79b5
4c79b5
\item[formatText:] The \texttt{formatText} function, let you format
4c79b5
plain text files. This function uses the GNU's \texttt{fmt} tool as
4c79b5
base to do all modifications.
4c79b5
4c79b5
\end{description}
4c79b5
4c79b5
\subsection{getMatchingList}
4c79b5
\hypertarget{sec:Concepts:Scripts:Function:getMatchingList}{}
4c79b5
\label{sec:Concepts:Scripts:Function:getMatchingList}
4c79b5
4c79b5
The matching list specifies the relation between design templates and
4c79b5
translation files that artwork components have. The
4c79b5
\texttt{renderImage} and \texttt{renderText} functions require this
4c79b5
information in order to work properly. 
4c79b5
4c79b5
Initially, the matching list was defined explicitly and independently
4c79b5
inside each artwork component's configuration script. Later, as many
4c79b5
of these components had just the same configuration stuff, the code
4c79b5
was reduced and unified inside \texttt{getMatchingList} function.
4c79b5
Inside \texttt{getMatchingList}, there is a case selection statement
4c79b5
where specific matching lists cases are defined, and one default
4c79b5
behaivour that match in thoses cases where none else does.  
4c79b5
4c79b5
The matching list code reduction changed the way you customize artwork
4c79b5
component's matching list.  From now on, you look inside configuration
4c79b5
files to be sure that \texttt{ARTCOMP} variable refers to the
4c79b5
appropriate artwork component, and inside \texttt{getMatchingList}
4c79b5
function to define its matching list.  For example, when rendering
4c79b5
Anaconda progress, its matching list specifies which translation files
4c79b5
apply which design templates. So, to change the matching list of this
4c79b5
artwork component, you need to edit the function
4c79b5
\texttt{getMatchingList} and set the appropriate relation there, in
4c79b5
the Anaconda progress matching list specification.
4c79b5
4c79b5
When setting artwork components' matching list, you can use any of the
4c79b5
following configuration available:
4c79b5
4c79b5
\begin{description}
4c79b5
4c79b5
\item[Configuration 1:] Specific translation files are applied to
4c79b5
specific design templates. In this configuration you have detailed
4c79b5
control over which translation files are applied to which design
4c79b5
template.
4c79b5
4c79b5
\begin{verbatim}
4c79b5
MATCHINGLIST="\
4c79b5
design-template-A.svg: translation-file-1.sed translation-file-2.sed
4c79b5
design-template-B.svg: translation-file-3.sed translation-file-4.sed
4c79b5
"
4c79b5
\end{verbatim}
4c79b5
4c79b5
Another way to write the previous example is: 
4c79b5
4c79b5
\begin{verbatim}
4c79b5
MATCHINGLIST="\
4c79b5
design-template-A.svg:\
4c79b5
   translation-file-1.sed\
4c79b5
   translation-file-2.sed
4c79b5
design-template-B.svg:\
4c79b5
   translation-file-3.sed\
4c79b5
   translation-file-4.sed
4c79b5
"
4c79b5
\end{verbatim}
4c79b5
4c79b5
In the above examples translation files 1 and 2 apply
4c79b5
design-template-A.svg. Likewise, translation files 3 and 4 apply
4c79b5
design-template-B.svg. That was a simple case, but what about if you
4c79b5
have hundreds of translation files to apply to specific design
4c79b5
templates? Lets say, translation files from 1 to 49 apply
4c79b5
design-template-A.svg and translation files from 50 to 99 apply
4c79b5
design-template-B.svg.  It would be tiresome to write down the name of
4c79b5
every single file in the above configuration. In these situations you
4c79b5
can ``generate'' the translation files as shown below: 
4c79b5
4c79b5
\begin{verbatim}
4c79b5
MATCHINGLIST="\
4c79b5
design-template-A.svg:\
4c79b5
   $(for NUMBER in $(sed 1 49);do
4c79b5
      echo -n translation-file-${NUMBER}.sed ' '
4c79b5
     done)
4c79b5
design-template-B.svg:\
4c79b5
   $(for NUMBER in $(sed 50 99);do
4c79b5
      echo -n translation-file-${NUMBER}.sed ' '
4c79b5
     done)
4c79b5
"
4c79b5
\end{verbatim}
4c79b5
4c79b5
Another interesting case is when you need to apply hundreds of
4c79b5
translation files to hundreds of design templates, in a file structure
4c79b5
where they both share a common bond path.  That is the
4c79b5
\texttt{Identity/Brands} artwork component case.  Writing down such a
4c79b5
matching list consumes lot of time.  So you can ``generate'' the
4c79b5
entire matching list like the following:
4c79b5
4c79b5
\begin{verbatim}
4c79b5
MATCHINGLIST="\
4c79b5
$(for TEMPLATE in $(find $(getPath 'trunk/Identity/Brands')/tpl \
4c79b5
   -name '*.svg' | sed -r 's!.*/Brands/Tpl/(.*)$!\1!' | sort );do
4c79b5
4c79b5
   TRANSLATION=$(find $(getPath \
4c79b5
      'trunk/Translations/Identity/Brands')/$(echo $TEMPLATE \
4c79b5
      | sed 's!\.svg!!') -name '*.sed' \
4c79b5
      | sed -r 's!^.*/Brands/(.*)$!\1!' \
4c79b5
      | sort | tr '\n' ' ')
4c79b5
4c79b5
   echo $TEMPLATE: $TRANSLATION
4c79b5
   done)
4c79b5
"
4c79b5
\end{verbatim}
4c79b5
4c79b5
\item[Configuration 2:] All translation files are applied to a single
4c79b5
design template.  In this configuration all artwork component's
4c79b5
translation files are applied to one design template
4c79b5
(design-template-A.svg for the matter of this case).
4c79b5
4c79b5
\begin{verbatim}
4c79b5
MATCHINGLIST="design-template-A.svg"
4c79b5
\end{verbatim}
4c79b5
4c79b5
\item[Configuration 3:] Translation files are applied to design
4c79b5
templates that share a common name. In this configuration translation
4c79b5
files are applied to design templates taking the name part, without
4c79b5
extension, as reference.  This means that, if you have a translation
4c79b5
file named \texttt{File-1.sed} you need to have a \texttt{File-1.svg}
4c79b5
inside design templates. This way, \texttt{File-1.sed} can be applied
4c79b5
to \texttt{File-1.svg} and, as result, produce the \texttt{File-1.png}
4c79b5
file.  This is the default matching list behaivour.
4c79b5
4c79b5
\begin{verbatim}
4c79b5
MATCHINGLIST=""
4c79b5
\end{verbatim}
4c79b5
4c79b5
\end{description}
4c79b5
4c79b5
\subsection{getPath}
4c79b5
4c79b5
The \texttt{getPath} function creates the artwork component's absolute
4c79b5
path. Before output the absolute path, \texttt{getPath} removes any
4c79b5
``strange'' character from the final path. For \texttt{getPath} to
4c79b5
work, the relative path to the artwork component should be provided
4c79b5
from \texttt{trunk/}'s directory level on.