Blame Manuals/Latex/centos-art.sh-latex/Concepts/scripts.tex

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