The render functionality exists to automate production of files inside the working copy. Specifically, the render functionality is aimed to produce text-based and image-based files in different information levels (i.e., different languages, release numbers, architectures, etc.).

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

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 centos-art.sh to an identity directory structure. If such identity directory structure doesn't exist, then it is good time to create it. Each identity directory structure represents one visual manifestation of CentOS corporate visual identity.

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 trunk/Identity/ or 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 Tpl/ directory to store design template files, one 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.

Inside renderable identity directory structures, centos-art.sh can render both image-based and text-based files. Specification of whether a renderable identity directory structure produces image-based or text-based content is a configuration action that takes place in the pre-rendition configuration script of that renderable identity directory structure.

Inside renderable identity directory structures, content production is organized in different configurations. A content production configuration is a unique combination of the components that make an identity directory structure renderable. One content production configuration does one thing only (e.g., to produce untranslated images), but it can be extended (e.g., adding translation files) to achieve different needs (e.g., to produce translated images).

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 file-type and file-extension.

For example, to produce images without translations (there is no much use in producing text-based files without translations), consider the following configuration:

One renderable identity directory structure:

     In this example we used Identity/Path/To/Dir as the identity component we want to produce untranslated images for.  Identity components can be either under trunk/ or branches/ directory structure.

     The identity component (i.e., Identity/Path/To/Dir, in this case) is also the bond component we use to connect the identity directory structures with their respective auxiliar directories (i.e., translation directory structres and pre-rendition configuration structures).  The bond component is the path convenction that centos-art.sh uses to know where to look for related translations, configuration scripts and whatever auxiliar thing a renderable directory structure may need to have.

           | The bond component
           |----------------->|
     trunk/Identity/Path/To/Dir  <-- Renderable identity directory structure.
     |-- Tpl                     <-- Design template directory.
     |   `-- file.svg            <-- Design template file.
     `-- Img                     <-- Directory used to store final files.
         `-- file.png            <-- Final image-based file produced from
                                     design template file.

     Inside design template directory, design template files are based on SVG (Scalable Vector Graphics) and use the extension .svg.  Design template files can be organized using several directory levels to create a simple but extensible configuration, specially if translated images are not required.

     In order for 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 CENTOSARTWORK object id inside.

     The CENTOSARTWORK word itself is a convenction name we use to define which object/design area, inside a design template, the centos-art.sh script will use to export as PNG (Portable Network Graphic) image at rendition time. Whithout such object id specification, the centos-art.sh script cannot know what object/design area you (as designer) want to export as PNG (Portable Network Graphic) image file.

          Note At rendition time, the content of Img/ directory structure is produced by centos-art.sh automatically.

     When a renderable identity directory structure is configured to produce image-based content, centos-art.sh produces PNG (Portable Network Graphics) files with the .png extension. Once the base image format has been produced, it is possible for centos-art.sh to use it in order to automatically create other image formats that may be needed (see trunk Scripts Bash Functions Render Config).

     Inside the working copy, you can find an example of ``design template without translation'' configuration at trunk/Identity/Models/.

     See trunk Identity, for more information.

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 to process the identity renderable directory entry.

     If the translation entry is empty (i.e., there is no file inside it), centos-art.sh interprets the identity renderable directory structure as a ``design templates without translation'' configuration.

                        | The bond component
                        |----------------->|
     trunk/Translations/Identity/Path/To/Dir
     `-- (empty)

     If the translation entry is not empty, centos-art.sh can interpret the identity renderable directory structure as one of the following configurations: ``design template with translation (one-to-one)'' or ``design template with translation (optimized)''. Which one of these configurations is used depends on the value assigned to the matching list (MATCHINGLIST) variable in the pre-rendition configuration script of the renderable identity directory structure we are producing images for.

     If the matching list variable is empty (as it is by default), then ``design template with translation (one-to-one)'' configuration is used. In this configuration it is required that both design templates and translation files have the same file names. This way, one translation files is applied to one design template, to produce one translated image.

     If the matching list variable is not empty (because you redefine it in the pre-rendition configuration script), then ``design template with translation (optimized)'' configuration is used instead. In this configuration, design templates and translation files don't need to have the same names since such name relationship between them is specified in the matching list properly.

     See trunk Translations, for more information.

One pre-rendition configuration script:

     In order to make an identity directory structure renderable, a pre-rendition configuration script should exist for it.  The pre-rendition configuration script specifies what type of rendition does centos-art.sh will perform over the identity directory structure and how does it do that.

                                                | The bond component
                                                |----------------->|
     trunk/Scripts/Bash/Functions/Render/Config/Identity/Path/To/Dir
     `-- render.conf.sh

     In this configuration the pre-rendition configuration script (render.conf.sh) would look like the following:

     function render_loadConfig {

         # Define rendition actions.
         ACTIONS[0]='BASE:renderImage'

     }

     Since translation directory structure is empty, centos-art.sh assumes a ``design template without translation'' configuration to produce untranslated images.

     To produce untranslated images, centos-art.sh takes one design template and creates one temporal instance from it.  Later, centos-art.sh uses the temporal design template instance as source file to export the final untranslated image. The action of exporting images from SVG (Scalable Vector Graphics) to PNG (Portable Network Graphics) is possible thanks to Inkscape's command-line interface and the CENTOSARTWORK object id we previously set inside design templates.

     centos-art.sh render --identity=trunk/Identity/Path/To/Dir
     -------------------------------------------------
     0 | Execute centos-art.sh on renderable identity directory structure.
     --v----------------------------------------------
     trunk/Identity/Path/To/Dir/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.

     Finally, when the untranslated image has been created, the temporal design template instance is removed. At this point, centos-art.sh takes the next design template and repeats the whole production flow once again (design template by design template), until all design templates be processed.

     See trunk Scripts Bash Functions Render Config, for more information.

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 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, centos-art.sh will not produce the final image related to the missing component.

In order for 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 trunk/Translations/Identity/Path/To/Dir/file.sed translation file does match trunk/Identity/Path/To/Dir/Tpl/file.svg design template, but it doesn't match trunk/Identity/Path/To/Dir/File.svg or trunk/Identity/Path/To/Dir/Tpl/File.svg or trunk/Identity/Path/To/Dir/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.

     Note If we use no translation file in the translation entry (i.e., an empty directory), centos-art.sh assumes the untranslated image production. If we fill the translation entry with translation files, centos-art.sh assumes the translated image production.

To produce final images, centos-art.sh applies one translation file to one design template and produce a translated design template instance. Later, centos-art.sh uses the translated template instance to produce the translated image. Finally, when the translated image has been produced, centos-art.sh removes the translated design template instance. This production flow is repeated for each translation file available in the translatio entry.

centos-art.sh render --identity=trunk/Identity/Path/To/Dir
-------------------------------------------------
0 | Execute centos-art.sh on directory structure.
--v----------------------------------------------
trunk/Translations/Identity/Path/To/Dir/file.sed
-------------------------------------------------
1 | Apply translation to design template.
--v----------------------------------------------
trunk/Identity/Path/To/Dir/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.

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 (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 MATCHINGLIST variable is set in the pre-rendition configuration script of the component we want to produce images for. By default, the MATCHINGLIST variable is empty which means no matching list is used. Otherwise, if MATCHINGLIST variable has a value different to empty value then, 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:

One entry under trunk/Identity/:

     In this configuration we want to produce three images using a paragraph-based style, controlled by paragraph.svg design template; and one image using a list-based style, controlled by list.svg design template.

     trunk/Identity/Path/To/Dir
     |-- Tpl
     |   |-- paragraph.svg
     |   `-- list.svg
     `-- Img
         |-- 01-welcome.png
         |-- 02-donate.png
         |-- 03-docs.png
         `-- 04-support.png

One entry under 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.

     trunk/Translations/Identity/Path/To/Dir
     |-- 01-welcome.sed
     |-- 02-donate.sed
     |-- 03-docs.sed
     `-- 04-support.sed

One entry under 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 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 MATCHINGLIST variable inside the pre-rendition configuration script of the component we want to produce images for.

     trunk/Scripts/Bash/Functions/Render/Config/Identity/Path/To/Dir
     `-- render.conf.sh

     In this configuration the pre-rendition configuration script (render.conf.sh) would look like the following:

     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
         "

     }

     As result, centos-art.sh will produce 01-welcome.png, 02-donate.png and 04-support.png using the paragraph-based design template, but 03-docs.png using the list-based design template.

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 almost does.

Generally, we use design templates to define how final images will look like. Generally, each renderable directory structure has one 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 centos-art.sh.

For example, consider the following configuration:

One entry under 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 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.

                             THEMEMODEL | | The bond component
                                  |<----| |--------------------->|
     trunk/Identity/Themes/Models/Default/Distro/Anaconda/Progress/
     |-- paragraph.svg
     `-- list.svg

     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.

One entry under 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 centos-art.sh (e.g., Backgrounds, Color information, Screenshots, etc.).

                       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

One entry under 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.

                                        | The bond 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

One entry under 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 centos-art.sh how to render the component.

     trunk/Scripts/Bash/Functions/Render/Config/Identity/Themes/Distro/Anaconda/Progress/
     `-- render.conf.sh

     In this configuration the pre-rendition configuration script (render.conf.sh) would look like the following:

     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'

     }

The production flow of ``optimize+flexibility'' configuration...

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 (Tpl/) directory structure to handle common content inside translation files.  This way, we work on translation templates and later use 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 centos-art.sh is executed to produce translation files from translation templates.

Inside renderable translation directory structures, centos-art.sh can produce text-based files only.

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:

 1. To have a unique directory structure under trunk/Identity, organized by any one of the above organizational designs above.

 2. To have a unique directory structure under trunk/Translations to store translation files.

 3. To have a unique directory structure under trunk/Scripts/Bash/Functions/Render/Config to set pre-rendition configuration script.

As convenction, the render_doCopy function uses trunk/Identity directory structure as source location.  Once the 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 FLAG_TO variable.

Design templates + No translation:

Command: - centos-art render --copy=trunk/Identity/Path/To/Dir --to=trunk/Identity/NewPath/To/Dir

Sources: - trunk/Identity/Path/To/Dir - trunk/Translations/Identity/Path/To/Dir - trunk/Scripts/Bash/Functions/Render/Config/Identity/Path/To/Dir

Targets: - trunk/Identity/NewPath/To/Dir - trunk/Translations/Identity/NewPath/To/Dir - trunk/Scripts/Bash/Functions/Render/Config/Identity/NewPath/To/Dir

Renderable layout 2:

Command: - centos-art render --copy=trunk/Identity/Themes/Motifs/TreeFlower \ --to=trunk/Identity/Themes/Motifs/NewPath/To/Dir

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/NewPath/To/Dir - trunk/Translations/Identity/Themes - trunk/Translations/Identity/Themes/Motifs/NewPath/To/Dir - trunk/Scripts/Bash/Functions/Render/Config/Identity/Themes - trunk/Scripts/Bash/Functions/Render/Config/Identity/Themes/Motifs/NewPath/To/Dir

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.

Usage
-----

  * ...

See also
--------