| % 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. |
| |