@subheading NAME

This section describes the @code{render} functionality of
@command{centos-art.sh} script and general examples about content
rendition inside a working copy of CentOS Artwork Repository.

@subheading SYNOPSIS

@command{centos-art render [] path/to/dir}

The @file{path/to/dir} parameter refers the path information related
to the directory structure inside the working copy of CentOS Artwork
Repository you'r going to produce.  This path information defines
whether to perform direct or theme-specific rendition.

You can use the @file{path/to/dir} information to control the amount
of components you'll produce inside a specific renderable location.
The more deep you go inside the path the more specific you are when
producing theme components. Sometimes, you can also combine the use of
@file{path/to/dir} with the @option{--filter} option to have a finer
control over the files you produce.

@subheading DESCRIPTION

The @code{render} functionlity of @command{centos-art.sh} script
standardizes rendition tasks inside the working copy of CentOS Artwork
Repository.  

Inside the working copy of CentOS Artwork Repository, rendition tasks
take place inside renderable directories.  Inside the @code{render}
functionality of @command{centos-art.sh} script, you can control
rendition tasks through different flows of rendition named
base-rendition, post-rendition, last-rendition and directory-specific
rendition.

@subsubheading Renderable directories

In order for a directory structure to be considered renderable, it
should have one directory structure for input files and one directory
structure for output files. Optionally, a third directory structure
might be available for storing translation files.

Renderable directories are very tied to the way content is produced
inside the working copy of CentOS Artwork Repository. Presently,
content is produced through the following organizations:

@table @strong
@item Direct rendition

In direct rendition, there is one directory structure for input files
(@file{trunk/Identity/Models}) and one directory structure for output
files (e.g., @file{trunk/Identity/Images}). Optionally, a third
directory structure is available to store the input related
translation files (e.g., @file{trunk/Locales/Identity/Models}).

In direct rendition, when the @code{render} functionality of
@command{centos-art.sh} script is executed, it uses the input
directory structure to build a list of files to process, which is used
as reference to determine the location of the translation file and the
location of the output file, as well.

@item Theme-specific rendition

In theme-specific rendition, there is one directory structure to store
input files @file{trunk/Identity/Themes/Models}, one directory
structure to store translation files
(@file{trunk/Locales/Identity/Themes/Models/}), one directory structure
to store artistic motifs (@file{trunk/Identity/Images/Themes}) and one
directory structure to store output files
(@file{trunk/Identity/Images/Themes}).

In theme-specific rendition, when the @code{render} functionality of
@command{centos-art.sh} script is executed, it uses the input
directory structure to build a list of files to process, which is used
as reference to determine the location of the translation file and the
location of the output file, as well. 

In contrast with direct rendition, when we use theme-specific
rendition, it is possible to combine both design models and artistic
motifs to produce output in an arbitrary way. This configuration is
specially interesting because it is possible to create different
artistic motifs and one unique design model in order to produce one
unique theme structure with different visual styles. Or the opposite,
to create different theme structures and apply one unique visual style
to produce different visual styles with the same theme structure. Or
even push a bit farther and experiment with arbitrary combinations
among them all.

@end table

In both direct and theme-specific rendition, if the location where the
output file should be stored doesn't exist, the @code{render}
functionality of @command{centos-art.sh} script will create it for
you.

In both direct and theme-specific rendition, if the input related
translation file doesn't exist, the @code{render} functionality of
@command{centos-art.sh} script will produce the output in the same
language of its input file.

@subsubheading The base-rendition flow

The base-rendition flow is the first rendition flow of all rendition
flows available and takes place immediatly after executing the
@code{render} functionality of @command{centos-art.sh} script.

The base-rendition consist on producing different output formats in
different languages from one single input format.  This is, one input
file produces one output file. Inside the @code{render} functionality
of @command{centos-art.sh} script, the input format is always an XML
file (e.g., SVG, XHTML, Docbook) and the output format depends on the
input file provided.  

For example, when the input format is a SVG file, the base output is a
PNG file; when the input format is XHTML the base output is an XHTML
file; when the input format is a Docbook file the base output is an
XHTML file.

@subsubheading The post-rendition flow

The post-rendition flow takes place after base-rendition and is
applied to create modified copies of the file produced by
base-rendition in the same directory structure.

For example, when the input format is a SVG file and the output is a
PNG file, we can use post-rendition to extend the base output to other
image formats. In fact, it is possible to do anything permitted by the
ImageMagick and Netpbm programs (e.g., resize, rotate, reduce color,
etc.) over the base output. 

@subsubheading The last-rendition flow

The last-rendition flow takes place after post-rendition and is
applied to all files produced as result of both base-rendition and
post-rendition flows in the same directory structure, just before
passing to process a different directory structure.

For example, consider the @file{Preview.png} image of Ksplash which is
made of three different images. In order to build the
@file{Preview.png} image, we need to create the three images the
@file{Preview.png} image is made of first (e.g., through
base-rendition) and then, combine them all together into one new
image, the @file{Preview.png} image in this case.

Another example of using last-rendition flow is that related to GDM
and KDM @file{tar.gz} file construction. Each @file{tar.gz} file is
made of several files that need to be put together in order to make
them installable. In the very specific case of GDM and KDM some of the
required files are retrived from design models directory structure and
others from artistic motifs directory structure after had been
produced through base-rendition. In this case, the action of grouping
files and packing them is realized through last-rendition action. This
couldn't be possible through post-rendition because we need to wait to
have two images first (produced through base-rendition) before we
could grouping them all into the @file{tar.gz} package.

@subsubheading The directory-specific rendition flow

The directory-specific rendition flow isn't a rendition flow by itself
but a combination of rendition flows that are applied to specific
directories at rendition time.

Inside the working copy of CentOS Artwork Repository there are some
directories structures that exist to achieve specific tasks every time
they are produced. The directory-specific rendition flow provides a
way for the @code{render} functionality of @command{centos-art.sh}
script to know what actions to apply to what directory structure when
producing them.

The directory-specific rendition flow combines the base-rendition,
post-rendition and last-rendition flows in specific ways and applies
them to specific directory structures when they are detected.  Using
this configuration can speed up production of different components
like Syslinux, Grub, Gdm, Kdm and Ksplash that require intermediate
formats or even several independent files, in order for the final
content to be created.  

@subsubheading Translations

To translate output files, the @code{render} functionality of
@command{centos-art.sh} script creates a translated instance of the
input file and uses it then to create the base output file. The
translated instance is created using the related translation messages
of the input file. Translation messages are stored under
@file{trunk/Locales} and are created using the @code{locale}
functionality of @command{centos-art.sh} script (@pxref{Directories
trunk Scripts Functions Locale}).

@subheading OPTIONS

The @code{render} functionality of @command{centos-art.sh} script
accepts the following optios:

@table @option
@item --quiet

Supress all output messages, including confirmation question. Use this
option with care.

@item --filter="REGEX"

Reduce the list of files to process using @samp{REGEX} as pattern.

@item --answer-yes

Assume `yes' to all confirmation questions.

@item --dont-commit-changes

Supress all commit and update actions realized over files already
processed, before and after the action itself had took place in the
working copy.

@item --releasever="STRING"

Produce content for the release version specified in @samp{STRING}.
This option is generaly used in direct rendition, where design models
aren't organized using release versions and architectures as
reference.

@item --basearch="STRING"

Produce content for the architecture specified in @samp{STRING}.  This
option is generaly used in direct rendition, where design models aren't
organized using release versions and architectures as reference.

@item --convert="STRING"

Uses post-rendition to convert output produced by base-rendition to
any image format specified in @samp{STRING}. This option is an
interface for the @command{convert} command of ImageMagick tool set,
so it is applicable to images output only.

@item --rotate="STRING"

Uses post-rendition to rotate output produced by base-rendition to any
angle specified in @samp{STRING}. This option is an interface for the
@command{convert} command of ImageMagick tool set, so it is
applicable to images output only.

@item --resize="STRING"

Uses post-rendition to resize the base-rendition output to any angle
specified in @samp{STRING}. This option is an interface for the
@command{convert} command of ImageMagick tool set, so it is applicable
to images output only.

@item --group-by="STRING"

Group base output files inside directories. Directories used to stored
base output files are named using the file extension of base output
files.  For example: if the base output file is a @file{.png} file, it
is moved inside a @file{Png/} directory; if the current file is a
@file{.jpg} file, it is stored inside a @file{Jpg/} directory, and so
on.

Directories used to group files are created in the same location that
base output files would normaly do.

@item --theme-model="STRING"
Specify, in the @samp{STRING}, the name of the theme model you want to
use to produce theme motifs. By default, if this option is not passed,
the @samp{Default} theme model is used as reference to produce theme
motifs. 
@end table

@subsubheading Examples

@table @command
@item centos-art render trunk/Identity/Images/Brands
@item centos-art render trunk/Identity/Images/Brands --filter="symbol"
@item centos-art render trunk/Identity/Images/Themes/Flame/2
@end table

@subheading AUTHOR

Copyright @copyright{}  2009, 2010, 2011 Alain Reguera Delgado.

@subheading See also

@itemize
@item @ref{Directories trunk Scripts Functions}
@item @ref{Directories trunk Scripts}
@item @ref{Directories trunk}
@end itemize