@subsection Goals

The @code{render} functionality exists to automate production of files

inside the working copy. The @code{render} functionality is aimed to

satisfy different file types (e.g., text-based and image-based)

production needs in different information levels (e.g., different

languages, release numbers, different architectures, etc.).

@subsection Description

The @code{render} functionality relies on ``renderable directory

structures'' to produce files. Renderable directory structures can be

either ``identity directory structures'' or ``translation directory

structures'' with special directories inside. 

@subsection Renderable identity directory structures

Identity directory structures are the starting point of identity

rendition. Whenever we want to render a component of CentOS corporate

visual identity we need to point @file{centos-art.sh} to an identity

directory structure. If such identity directory structure doesn't

exists, then it is good time to created. Each identity directory

structure represents one visual manifestation of CentOS corporate

visual identity. @xref{trunk Identity}, for more information.

The first requirement for an identity directory structure to be

considered a renderable identity directory structure is its location,

inside the working copy: it should be under @file{trunk/Identity/} or

@file{branches/Identity/} directory structure.

The second requirement for an identity directory structure to be

considered a renderable identity directory structure is its directory

structure: it needs to have one (@file{Tpl/}) directory to store

design templates files, one @file{Img/} directory to store files

produced as rendition result, one translation directory structure to

store translation files and one script directory to store

pre-rendition configuration scripts.  All these directory structures

are connected among themselves by a common component in their path

that bonds them altogether.  @xref{trunk Scripts Bash Functions Path},

for more information.

Inside renderable identity directory structures, @file{centos-art.sh}

can render image-based and text-based files. 

@subsubsection Design template without translation

The design template without translation configuration is based on a

renderable identity directory structure with an empty translation

directory structure. In this configuration, one design template

produces one untranslated file. Both design templates and final

untranslated files share the same file name, but they differ one

another in the file-type itself and the file-extension used to

describe the file type.

Design templates are based on @acronym{SVG,Scalable Vector Graphics}

and use the extension @code{.svg}.  Files produced as rendition result

(i.e., the final files translated or not) may be text-based files with

arbitrary extensions, or @acronym{PNG,Portable Network Graphics} files

with the extension @code{.png}.  Definition of whether a final file is

text-based or image-based is set in the pre-rendition configuration

script of the renderable directory structure we want to produce files

for.

For example, to produce images without translations (there is no much

use in producing text-based files without translations), consider the

following configuration:

@table @strong

@item One renderable identity directory structure:

Specify the identity component we want to produce images for.

@verbatim

trunk/Identity/DirName

|-- Tpl

|   `-- file.svg

`-- Img

    `-- file.png

@end verbatim

Inside design template directory, design template files can be

organized using several directory levels.  Using several levels of

directories inside design template directory let us to create very

simple but extensible configurations, specially if translated images

are not required.

@quotation

@strong{Note} When we use a ``design template without translation''

configuration,  @file{centos-art.sh} creates the @file{Img/} directory

structure automatically taking the @file{Tpl/} directory structure as

reference at rendition time.

@end quotation

In order for @acronym{SVG,Scalable Vector Graphics} files to be

considered ``design template'' files, they should be placed under the

design template directory and to have set a @code{CENTOSARTWORK}

object id inside.

The @code{CENTOSARTWORK} word itself is a convenction name we use to

define which object/design area, inside a design template, the

@file{centos-art.sh} script will use to export as PNG image at

rendition time.  Whithout such object id specification, the

@file{centos-art.sh} script cannot know what object/design area you

(as designer) want to export as PNG image file.

Inside the working copy, you can find an example of ``design template

without translation'' configuration at @file{trunk/Identity/Models/}.

@xref{trunk Identity}, for more information.

@item One translation directory structure:

In order for an identity entry to be considered an identity renderable

directory structure, it should have a translation entry. The content

of the translation entry is relevant to determine how the identity

renderable directory entry is processed.

If the translation entry is empty (i.e., there is no file inside it),

@file{centos-art.sh} interprets the identity renderable directory

structure as a ``design templates without translation'' configuration.

@verbatim

trunk/Translations/Identity/DirName

`-- (empty)

@end verbatim

If the translation entry is not empty, @file{centos-art.sh} can

interpret the identity renderable directory structure as any of the

following configuration: ``design templates with translations

(one-to-one)'' or ``design templates with translations (optimized)''.

Which one of these configuration is used depends on the value assigned

to the matching list (@var{MATCHINGLIST}) variable.

If the matching list variable is empty (as it is by default), then

``design templates with translations (one-to-one)'' configuration is

used. In this configuration it is required that both design templates

and translation files have the same file names. 

If the matching list variable is not empty (because you redefine it in

the pre-rendition configuration script), then ``design templates with

translations (optimized)'' configuration is used instead. In this

configuration, design templates and translation files don't need to

have the same names since such relation between them is specified in

the matching list properly.

@xref{trunk Translations}, for more information.

@item One pre-rendition configuration script:

In order to make an identity entry renderable, a pre-rendition

configuration script should exist for it.  The pre-rendition

configuration script specifies what type of rendition does

@file{centos-art.sh} will perform and the way it does it.

@verbatim

trunk/Scripts/Bash/Functions/Render/Config/Identity/DirName

`-- render.conf.sh

@end verbatim

In this configuration the pre-rendition configuration script

(@file{render.conf.sh}) would look like the following:

@verbatim

function render_loadConfig {

    # Define rendition actions.

    ACTIONS[0]='BASE:renderImage'

}

@end verbatim

To produce untranslated images, @file{centos-art.sh} takes one design

template and creates one temporal instance from it. Later,

@file{centos-art.sh} uses the temporal design template instance as

source file to export the final untranslated image. The export action

is possible thanks to Inkscape's command-line interface and the

@code{CENTOSARTWORK} object id we set inside design templates.

@verbatim

centos-art.sh render --identity=trunk/Identity/DirName

-------------------------------------------------

0 | Execute centos-art.sh on renderable identity directory structure.

--v----------------------------------------------

trunk/Identity/DirName/Tpl/file.svg

-------------------------------------------------

1 | Create instance from design template.

--v----------------------------------------------

/tmp/centos-art.sh-a07e824a-5953-4c21-90ae-f5e8e9781f5f-file.svg

-------------------------------------------------

2 | Render untranslated image from design template instance.

--v----------------------------------------------

trunk/Identity/NewDir/Img/file.png

-------------------------------------------------

3 | Remove design template instance.

@end verbatim

Finally, when the untranslated image has been created, the temporal

design template instance is removed. At this point, the next design

template in the list is taken to repeat the production flow once again

and so on, until all design templates be processed.

@xref{trunk Scripts Bash Functions Render Config}, for more

information.

@end table

@subsubsection Design template with translation (one-to-one)

Producing untranslated images is fine in many cases, but not always.

Sometimes it is required to produce images in different languages and

that is something that untrasnlated image production cannot achieve.

However, if we fill its empty translation entry with translation files

(one for each design template) we extend the production flow from

untranslated image production to translated image production.

In order for @file{centos-art.sh} to produce images correctly, each

design template should have one translation file and each translation

file should have one design template.  Otherwise, if there is a

missing design template or a missing translation file,

@file{centos-art.sh} will not produce the final image related to the

missing component.

In order for @file{centos-art.sh} to know which is the relation

between translation files and design templates the translation

directory structure is taken as reference.  For example, the

@file{trunk/Translations/Identity/DirName/file.sed} translation file

does match @file{trunk/Identity/DirName/Tpl/file.svg} design template,

but it doesn't match @file{trunk/Identity/DirName/File.svg} or

@file{trunk/Identity/DirName/Tpl/File.svg} or

@file{trunk/Identity/DirName/Tpl/SubDir/file.svg} design templates.

The pre-rendition configuration script used to produce untranslated

images is the same we use to produce translated images. There is no

need to modify it. So, as we are using the same pre-rendition

configuration script, we can say that translated image production is

somehow an extended/improved version of untranslated image production.

@quotation

@strong{Note} If we use no translation file in the translation entry

(i.e., an empty directory), @file{centos-art.sh} assumes the

untranslated image production. If we fill the translation entry with

translation files, @file{centos-art.sh} assumes the translated image

production.  

@end quotation

To produce final images, @file{centos-art.sh} applies one translation

file to one design template and produce a translated design template

instance. Later, @file{centos-art.sh} uses the translated template

instance to produce the translated image. Finally, when the translated

image has been produced, @file{centos-art.sh} removes the translated

design template instance. This production flow is repeated for each

translation file available in the translatio entry. 

@verbatim

centos-art.sh render --identity=trunk/Identity/DirName

-------------------------------------------------

0 | Execute centos-art.sh on directory structure.

--v----------------------------------------------

trunk/Translations/Identity/DirName/file.sed

-------------------------------------------------

1 | Apply translation to design template.

--v----------------------------------------------

trunk/Identity/DirName/Tpl/file.svg

-------------------------------------------------

2 | Create design template instance.

--v----------------------------------------------

/tmp/centos-art.sh-a07e824a-5953-4c21-90ae-f5e8e9781f5f-file.svg

-------------------------------------------------

3 | Render PNG image from template instance.

--v----------------------------------------------

trunk/Identity/NewDir/Img/file.png

-------------------------------------------------

4 | Remove design template instance.

@end verbatim

@subsubsection Design template with translation (optimized)

Producing translated images satisfies almost all our production images

needs, but there is still a pitfall in them. In order to produce

translated images as in the ``one-to-one'' configuration describes

previously, it is required that one translation file has one design

template. That's useful in many cases, but what would happen if we

need to apply many different translation files to the same design

template?  Should we have to duplicate the same design template file

for each translation file, in order to satisfy the ``one-to-one''

relation? What if we need to assign translation files to design

templates arbitrarily?

Certenly, that's something the ``one-to-one'' configuration cannot

handle.  So, that's why we had to ``optimize'' it. The optimized

configuration consists on using a matching list (@var{MATCHINGLIST})

variable that specifies the relationship between translation files and

design templates in an arbitrary way. Using such matching list between

translation files and design templates let us use as many assignment

combinations as translation files and design templates we are working

with.

The @var{MATCHINGLIST} variable is set in the pre-rendition

configuration script of the component we want to produce images for.

By default, the @var{MATCHINGLIST} variable is empty which means no

matching list is used. Otherwise, if @var{MATCHINGLIST} variable has a

value different to empty value then, @file{centos-art.sh} interprets

the matching list in order to know how translation files are applied

to design templates.

For example, consider the following configuration:

@table @strong

@item One entry under @file{trunk/Identity/}:

In this configuration we want to produce three images using a

paragraph-based style, controlled by @file{paragraph.svg} design

template; and one image using a list-based style, controlled by

@file{list.svg} design template.

@verbatim

trunk/Identity/DirName

|-- Tpl

|   |-- paragraph.svg

|   `-- list.svg

`-- Img

    |-- 01-welcome.png

    |-- 02-donate.png

    |-- 03-docs.png

    `-- 04-support.png

@end verbatim

@item One entry under @file{trunk/Translations/}:

In order to produce translated images we need to have one translation

file for each translated image we want to produce. Notice how

translation names do match final image file names, but how translation

names do not match design template names. When we use matching list

there is no need for translation files to match the names of design

templates, such name relation is set inside the matching list itself.

@verbatim

trunk/Translations/Identity/DirName

|-- 01-welcome.sed

|-- 02-donate.sed

|-- 03-docs.sed

`-- 04-support.sed

@end verbatim

@item One entry under @file{trunk/trunk/Scripts/Bash/Functions/Render/Config/}:

In order to produce different translated images using specific design

templates, we need to specify the relation between translation files

and design templates in a way that @file{centos-art.sh} could know

exactly what translation file to apply to what design template. This

relation between translation files and design templates is set using

the matching list @var{MATCHINGLIST} variable inside the pre-rendition

configuration script of the component we want to produce images for.  

@verbatim

trunk/Scripts/Bash/Functions/Render/Config/Identity/DirName

`-- render.conf.sh

@end verbatim

In this configuration the pre-rendition configuration script

(@file{render.conf.sh}) would look like the following:

@verbatim

function render_loadConfig {

    # Define rendition actions.

    ACTIONS[0]='BASE:renderImage'

    # Define matching list.

    MATCHINGLIST="\

    paragraph.svg:\

        01-welcome.sed\

        02-donate.sed\

        04-support.sed

    list.svg:\

        03-docs.sed

    "

}

@end verbatim

As result, @file{centos-art.sh} will produce @file{01-welcome.png},

@file{02-donate.png} and @file{04-support.png} using the

paragraph-based design template, but @file{03-docs.png} using the

list-based design template.

@end table

@subsubsection Design template with translation (optimized+flexibility)

In the production models we've seen so far, there are design templates

to produce untranslated images and translation files which combiend

with design templates produce translated images. That may seems like

all our needs are covered, doesn't it? Well, it @emph{almost} does.

Generally, we use design templates to define how final images will

look like. Generally, each renderable directory structure has one

@file{Tpl/} directory where we organize design templates for that

identity component. So, we can say that there is only one unique

design template definition for each identity component; or what is the

same, said differently, identity components can be produced in one way

only, the way its own design template directory specifies.  This is

not enough for theme production. It is a limitation, indeed.

Initially, to create one theme, we created one renderable directory

structure for each theme component. When we found ourselves with many

themes, and components inside them, it was obvious that the same

design model was duplicated inside each theme. As design models were

independently one another, if we changed one theme's design model,

that change was useless to other themes. So, in order to reuse design

model changes, we unified design models into one common directory

structure.

With design models unified in a common structure, another problem rose

up. As design models also had the visual style of theme components,

there was no difference between themes, so there was no apparent need

to have an independent theme directory structure for each different

theme.  So, it was also needed to separate visual styles from design

models.

At this point there are two independent worklines: one directory

structure to store design models (the final image characteristics

[i.e., dimensions, translation markers, etc.]) and one directory

structure to store visual styles (the final image visual style [i.e.,

the image look and feel]).  So, it is possible to handle both

different design models and different visual styles independtly one

another and later create combinations among them using

@file{centos-art.sh}. 

For example, consider the following configuration:

@table @strong

@item One entry under @file{trunk/Identity/Themes/Models/}:

The design model entry exists to organize design model files (similar

to design templates). Both design models and design templates are very

similar; they both should have the @code{CENTOSARTWORK} export id

present to identify the exportation area, translation marks, etc.

However, design models do use dynamic backgrounds inclusion while

design templates don't.

@verbatim

                        THEMEMODEL | | Design model component

                             |<----| |--------------------->|

trunk/Identity/Themes/Models/Default/Distro/Anaconda/Progress/

|-- paragraph.svg

`-- list.svg

@end verbatim

Inisde design models, dynamic backgrounds are required in order for

different artistic motifs to reuse common design models. Firstly, in

order to create dynamic backgrounds inside design models, we import a

bitmap to cover design model's background and later, update design

model's path information to replace fixed values to dynamic values.

@item One entry under @file{trunk/Identity/Themes/Motifs/}:

The artistic motif entry defines the visual style we want to produce

images for, only. Final images (i.e., those built from combining both

design models and artistic motif backrounds) are not stored here, but

under branches directory structure. In the artistic motif entry, we

only define those images that cannot be produced automatically by

@file{centos-art.sh} (e.g., Backgrounds, Color information,

Screenshots, etc.).

@verbatim

                  Artistic motif name | | Artistic motif backgrounds

                             |<-------| |-------->|

trunk/Identity/Themes/Motifs/TreeFlower/Backgrounds/

|-- Img

|   |-- Png

|   |   |-- 510x300.png

|   |   `-- 510x300-final.png

|   `-- Jpg

|       |-- 510x300.jpg

|       `-- 510x300-final.jpg

|-- Tpl

|   `-- 510x300.svg

`-- Xcf

    `-- 510x300.xcf

@end verbatim

@item One entry under @file{trunk/Translations/}:

The translation entry specifies, by means of translation files, the

language-specific information we want to produce image for. When we

create the translation entry we don't use the name of neither design

model nor artistic motif, just the design model component we want to

produce images for.

@verbatim

                                   | Design model component

                                   |--------------------->|

trunk/Translations/Identity/Themes/Distro/Anaconda/Progress/

`-- 5

    |-- en

    |   |-- 01-welcome.sed

    |   |-- 02-donate.sed

    |   `-- 03-docs.sed

    `-- es

        |-- 01-welcome.sed

        |-- 02-donate.sed

        `-- 03-docs.sed

@end verbatim

@item One entry under @file{trunk/Scripts/Bash/Functions/Render/Config/}:

There is one pre-rendition configuration script for each theme

component. So, each time a theme component is rendered, its

pre-rendition configuration script is evaluated to teach

@file{centos-art.sh} how to render the component.

@verbatim

trunk/Scripts/Bash/Functions/Render/Config/Identity/Themes/Distro/Anaconda/Progress/

`-- render.conf.sh

@end verbatim

In this configuration the pre-rendition configuration script

(@file{render.conf.sh}) would look like the following:

@verbatim

function render_loadConfig {

    # Define rendition actions.

    ACTIONS[0]='BASE:renderImage'

    # Define matching list.

    MATCHINGLIST="\

    paragraph.svg:\

        01-welcome.sed\

        02-donate.sed

    list.svg:\

        03-docs.sed

        "

    # Deifne theme model.

    THEMEMODEL='Default'

}

@end verbatim

@end table

The production flow of ``optimize+flexibility'' configuration@dots{}

@subsection Renderable translation directory structures

Translation directory structures are auxiliar structures of renderable

identity directory structures. There is one translation directory

structure for each renderable identity directory structure.  Inside

translation directory structures we organize translation files used by

renderable identity directory structures that produce translated

images. Renderable identity directory structures that produce

untranslated images don't use translation files, but they do use a

translation directory structure, an empty translation directory

structure, to be precise.

In order to aliviate production of translation file, we made

translation directory structures renderable adding a template

(@file{Tpl/}) directory structure to handle common content inside

translation files.  This way, we work on translation templates and

later use @file{centos-art.sh} to produce specific translation files

(based on translation templates) for different information (e.g.,

languages, release numbers, architectures, etc.).  

If for some reason, translation files get far from translation

templates and translation templates become incovenient to produce such

translation files then, care should be taken to avoid replacing the

content of translation files with the content of translation templates

when @file{centos-art.sh} is executed to produce translation files

from translation templates.

Inside renderable translation directory structures,

@file{centos-art.sh} can produce text-based files only.

@subsection Copying renderable directory structures 

A renderable layout is formed by design models, design images,

pre-rendition configuration scripts and translations files. This way,

when we say to duplicate rendition stuff we are saying to duplicate

these four directory structures (i.e., design models, design images,

pre-rendition configuration scripts, and related translations files).

When we duplicate directories, inside `trunk/Identity' directory

structure, we need to be aware of renderable layout described above

and the source location used to perform the duplication action.  The

source location is relevant to centos-art.sh script in order to

determine the required auxiliar information inside directory

structures that need to be copied too (otherwise we may end up with

orphan directory structures unable to be rendered, due the absence of

required information).

In order for a renderable directory structure to be valid, the new

directory structure copied should match the following conditions:

@enumerate

@item To have a unique directory structure under

@file{trunk/Identity}, organized by any one of the above

organizational designs above.

@item To have a unique directory structure under

@file{trunk/Translations} to store translation files.

@item To have a unique directory structure under

@file{trunk/Scripts/Bash/Functions/Render/Config} to set pre-rendition

configuration script.

@end enumerate

As convenction, the @code{render_doCopy} function uses

@file{trunk/Identity} directory structure as source location.  Once

the @file{trunk/Identity} directory structure has been specified and

verified, the related path information is built from it and copied

automatically to the new location specified by @var{FLAG_TO} variable.

Design templates + No translation:

Command:

- centos-art render --copy=trunk/Identity/DirName --to=trunk/Identity/NewDirName

Sources:

- trunk/Identity/DirName

- trunk/Translations/Identity/DirName

- trunk/Scripts/Bash/Functions/Render/Config/Identity/DirName

Targets:

- trunk/Identity/NewDirName

- trunk/Translations/Identity/NewDirName

- trunk/Scripts/Bash/Functions/Render/Config/Identity/NewDirName

Renderable layout 2:

Command:

- centos-art render --copy=trunk/Identity/Themes/Motifs/TreeFlower \

                    --to=trunk/Identity/Themes/Motifs/NewDirName

Sources:

- trunk/Identity/Themes/Motifs/TreeFlower

- trunk/Translations/Identity/Themes

- trunk/Translations/Identity/Themes/Motifs/TreeFlower

- trunk/Scripts/Bash/Functions/Render/Config/Identity/Themes

- trunk/Scripts/Bash/Functions/Render/Config/Identity/Themes/Motifs/TreeFlower

Targets:

- trunk/Identity/Themes/Motifs/NewDirName

- trunk/Translations/Identity/Themes

- trunk/Translations/Identity/Themes/Motifs/NewDirName

- trunk/Scripts/Bash/Functions/Render/Config/Identity/Themes

- trunk/Scripts/Bash/Functions/Render/Config/Identity/Themes/Motifs/NewDirName

Notice that design models are not included in source or target

locations. This is intentional. In ``Renderable layout 2'', design

models live by their own, they just exist, they are there, available

for any artistic motif to use. By default `Themes/Models/Default'

design model directory structure is used, but other design models

directory structures (under Themes/Models/) can be created and used

changing the value of THEMEMODEL variable inside the pre-rendition

configuration script of the artistic motif source location you want to

produce.

Notice how translations and pre-rendition configuration scripts may

both be equal in source and target. This is because such structures

are common to all artistic motifs (the default values to use when no

specific values are provided).

- The common directory structures are not copied or deleted. We cannot

  copy a directory structure to itself.

- The common directory structures represent the default value to use

  when no specific translations and/or pre-rendition configuration

  script are provided inside source location.

- The specific directory structures, if present, are both copiable and

  removable. This is, when you perform a copy or delete action from

  source, that source specific auxiliar directories are transfered in

  the copy action to a new location (that specified by FLAG_TO

  variable).

- When translations and/or pre-rendition configuration scripts are

  found inside the source directory structure, the centos-art.sh

  script loads common auxiliar directories first and later specific

  auxiliar directories.  This way, identity rendition of source

  locations can be customized idividually over the base of common

  default values.

- The specific auxiliar directories are optional.

- The common auxiliar directories should be present always. This is,

  in order to provide the information required by render functionality

  (i.e., to make it functional in the more basic level of its

  existence).

Notice how the duplication process is done from `trunk/Identity' on,

not the oposite. If you try to duplicate a translation structure (or

similar auxiliar directory structures like pre-rendition configuration

scripts), the `trunk/Identity' for that translation is not created.

This limitation is impossed by the fact that many `trunk/Identity'

directory structures may reuse/share the same translation directory

structure. We cannot delete one translation (or similar) directory

structures while a related `trunk/Identity/' directory structure is

still in need of it.

The `render_doCopy' functionality does duplicate directory structures

directly involved in rendition process only. Once such directories

have been duplicated, the functionality stops thereat. 

@subsection Usage

@itemize

@item ...

@end itemize

@subsection See also

@menu

* trunk Scripts Bash Functions Render Config::

@end menu