render(1)

=========

Name

----

render - Standardize production tasks.

Synopsis

--------

centos-art.sh render [OPTIONS] [DIRECTORY ...]

Description

-----------

The *render* module looks for configuration files inside the DIRECTORY

specified in the command-line and renders content based on

configuration files found inside it, if any. When no DIRECTORY is

specified, the *render* module looks for configuration files inside

the current directory it was executed from. If the current directory

is out of the working copy or no configuration file is found inside

the working copy DIRECTORY, the *render* module ends its execution

with an error message.

Options

-------

The *render* module accepts the following options:

*--help*::

    This option shows the *render* module's documentation (this page).

*--version*::

    This option shows the *render* module's name and version.

Configuration Files

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

The configuration files are regular files with the _.conf_ extension.

The name of configuration files is not relevant, though it might help

to remember what the configuration file is for. This way, and because

different modules can use configuration files for their own purposes,

the configuration files used by the *render* module are frequently

named as _render.conf_.

The format used by configuration files is common to all modules inside

*centos-art.sh* script. They all use configuration sections in the

form +[section-name]+ and configuration values in the form +option =

"value"+ to describe.  Based on the module being executed, the section

name and configuration values of configuration files might take

different meanings. In the specific case of *render* module, the

section name is always containing the name of the target file you want

to produce and the section-related configuration values always

describe the way you want to produce the file specified in the section

name.  Commentaries are also supported using the +#+ character a the

beginning of lines.  Commentaries defined this way are excluded from

processing so you can use them freely.

The configuration files can be divided in smaller configuration files

using name conventions. For example, if you have the file

_render.conf_, you can divide its content in _render-1.conf_,

_render-2.conf_ and so on. This sort of division is very useful when

the configuration file begins to grow, or you want to control the

order in which specific groups of files are produced inside the

DIRECTORY.

To describe the file's production, the *render* module's configuration

files accept the following configuration options:

*render-type*::

    Optional. This variable specifies the type or rendition the

    *render* module will perform. Possible values to this variable

    include _svg_, _asciidoc_, _symlink_. When this value is not

    specified or no value is set to it, the *render* module reads the

    value of *render-from* variable and determines what kind of

    rendition to perform based on the MIME information of the file

    provided.

*render-from*::

    Required. This variable specifies the file name of the source file

    (design model) used to produce the final file specified in the

    section line. This option can receive absolute paths and relative

    paths.  Absolute paths begin with a slash (+/+) character while

    relative paths begin with the dot slash (+./+) characters or no

    character at all.

*formats*::

    Optional. This variable specifies the different formats you want

    to create copies of the final file. The values specified in this

    variable are separated by white space and should be consequent

    with the production environment (e.g., image formats supported by

    ImageMagick when +render-type = "svg"+ and documentation formats

    supported by asciidoc when +render-type = "asciidoc"+). When this

    variable is not provided no duplicate copies in different formats

    are created,

    just the base file in its format.

*comment*::

    Optional. This variable specifies a section-specific comment

    describeing it.

Using Paths

~~~~~~~~~~~

When you provide absolute paths inside configuration files, there

isn't confusion about the location where the file is or should be.

However, it introduces rigidity to directory structures inside the

working copy when it is necessary to move directories from one place

to another inside the working copy.  To eliminate this mobility

restrictions, relative paths can be used to create modular directory

structures.

When you use relative paths inside configuration files, paths are

relative to the location where the configuration file is stored in.

This way it is possible to move whole directory structures without

touching the configuration file and still have a render-able

structures inside the working copy.  However, relative paths get

limited in situations where the production process needs files outside

the directory where the configuration file is stored in. In such

cases, a combination of relative and absolute paths is the solution to

apply.

When we need to use absolute paths to several files in the same

directory (e.g., we are combining them all to produce a new image) but

outside the current directory the configuration file is stored in, it

is possible to use a list of absolute paths one beside another

separated by space or we can use path expansion which is shorter and

easier to read.  Path expansion is interpreted when you enclose a list

of file names in curly brackets using comma as separator without

spaces (e.g., +{file1,file2,file3}+). In order for path expansion to

work correctly, all the file names you put inside the curly brackets'

list must exist in the location specified first.

Using Environment Variables

~~~~~~~~~~~~~~~~~~~~~~~~~~~

The configuration files let you to use environment variables inside

them. This might be very useful in situation where you need to provide

absolute paths based on specific information (e.g., your home

directory or the current locale information). To use environment

variables inside the configuration file you need to know the

environment variables used by *centos-art.sh* script and write them in

the form +${VARNAME}+, where +VARNAME+ is the name of the variable you

want to expand. Some of the most important environment variables used

by *centos-art.sh* script -and its configuration files- are described

below:

+TCAR_BASEDIR+::

    This variable contains the absolute path to your repository's

    working copy. The value of this variable is defined as read-only

    inside *centos-art.sh* script and cannot be modified later. As a

    matter of convenience, users make use of their +~/.bash_profile+

    file to define this variable there and, this way, skip the

    sometimes annoyance absolute path questioning the *centos-art.sh*

    script does in order to know the absolute path of the working copy

    it is going to work with.

+

Whenever you set absolute paths inside configuration files to refer

locations inside your working copy, it is necessary that you use the

+TCAR_BASEDIR+ environment variable in front of each path definition

you set.

+HOME+::

    This variable contains the absolute path to current user's home

    directory.  The value of this variable is set by the operating

    system when the user opens a terminal session.

+

Whenever you need to set user-specific absolute paths inside

configuration files, use this variable.

Rendering SVG Files

~~~~~~~~~~~~~~~~~~~

When the *render-type* variable is set to _svg_, the following

complementary variables can be used inside the configuration file:

*heights*::

    Optional. This variable specifies the different image heights you

    want to create copies of the final PNG image. The values specified

    in this variable are separated by white space and should be

    understandable by ImageMagick tool set. When this variable is not

    provided no duplicate copies in different heights will be

    produced. In this case the height information is taken from source

    file and just one PNG image is produced with it.

*fgcolors*::

    Optional. This variable specifies the different forground colors

    you want to create copies of the final PNG image. To do this, the

    image you want to copy should be rendered with black color

    (000000) so the color replacement can be performed. The values

    specified in this variable are separated by white space and should

    be understandable by ImageMagick tool set. When this variable is

    not provided no duplicate copies in different foreground colors

    are created.

*bgcolors*::

    Optional. This variable specifies the different background colors

    you want to create copies of the final PNG image. This variable

    plays with Inkscape's _--export-background_ and

    _--export-background-opacity_ options. Possible values to this

    functions take the form XXXXXX-X, where the first six X represent

    a color in hexadeciamal format and the final X might be 1 or 0. 1

    for full opacity and 0 for full transparency.  Intermediate values

    between 0 and 1 (e.g., 0.55) can be given to control the

    background opacity. When this variable is not provided no

    duplicate copies in different background colors are created.

*command*::

    Optional. This variable specifies the command used to perform the

    image manipulation. There are two options we've been using here

    both from ImageMagick tool set. The first option is

    +/usr/bin/convert+ command. This command creates copies of the

    image produced which is useful to create modified copies or

    combination of already existent images.  The second option is

    +/usr/bin/mogrify+ command.  This command modifies the PNG image

    inplace which might be useful when no modified duplications need

    to be created but just one modified image.  When this variable is

    not provided +/usr/bin/convert+ is used as default. Note that you

    can use this variable to pass options to image production (e.g.,

    to control whether images are combined horizotally or

    veritcally.).

Rendering Asciidoc Files

~~~~~~~~~~~~~~~~~~~~~~~~

When the *render-type* variable is set to _asciidoc_, the following

complementary variables can be used inside the configuration file:

Examples

--------

Here are some practical configuration files' examples you can use as

reference to create your own configuration files.

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

[corporate.docbook]

render-type = "asciidoc"

render-from = "corporate.asciidoc"

formats     = "xhtml pdf"

comment     = "The CentOS project corporate visual identity manual."

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

{asciidoc-br}

When the *render* module reads this configuration file, it creates the

+corporate.docbook+ file from +corporate.asciidoc+ file and later,

transforms the +corporate.docbook_ file into +corporate.html+ and

+corporate.pdf+ formats. The creation of files take place in the same

directory the configuration file was found. To control the location of

final files, you can use the section name of configuration files.

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

[centos-artwork.png]

render-from = "${TCAR_BASEDIR}/Artworks/Brands/Types/Webenv/centos.org/{centos,artwork}.svgz"

formats     = "xpm pdf jpg tif"

heights     = "16 20 22 24 32 36 38 40 48 64 72 78 96 112 124 128 148 164 196 200 512"

fgcolors    = "000000 ffffff"

bgcolors    = "ffffff-0"

command     = "/usr/bin/convert +append"

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

{asciidoc-br}

When the *render* module reads this configuration file, it takes the

+centos.svgz+ and +artwork.svgz+ files as source to produce the

+centos.png+ and +artwork.png+ files considering the first value in

the list of background and foreground colors specified in the

configuration file.  Then, it takes these PNG files and reduces their

sizes based on the *heights* variable and combines the results

horizontally to create the +centos-artwork.png+ file. Later, the

+centos-artwork.png+ file is converted to produce one image file for

each image format specified in the configuration file. At this point,

all the process repeats again but for the next height and color values

in the list.

{asciidoc-br}

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

[${HOME}/bin/centos-art]

render-type = "symbolic-link"

render-from = "centos-art.sh"

comment     = "The centos-art.sh script command."

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

When the *render* module reads this configuration file, it tries to

create the +${HOME}/bin/centos-art+ symbolic link from +centos-art.sh+

file. In case the +${HOME}/bin+ directory doesn't exist, it will be

created to favor the symbolic link creation. The *comment* variable

here hasn't any use here (except to describe what the section is for)

and you can get rid of it, if you want to.

Note how in this example we used an environment variable in the

section name definition.  This value will be expanded before the

*render* module could process the section name definition itself.  The

environment variables definitions can be used inside variable's

values, as well, but it is less common because most path references

inside configuration files are relative to the current location.

To identify a file is relative to current location, the repository

working copy or the system it is necessary to use a convention when

writing configuration files. 

Reporting Bugs

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

Report bugs on the *automation* category of *centos-artwork* project

at the https://centos.org.cu/bugs/[The CentOS Bugs] website.

Author

------

Written by mailto:al@centos.org.cu[Alain Reguera Delgado]

Copyright

---------

Copyright (C) 2013 The CentOS Project

This program is free software; you can redistribute it and/or modify

it under the terms of the GNU General Public License as published by

the Free Software Foundation; either version 2 of the License, or (at

your option) any later version.

This program is distributed in the hope that it will be useful, but

WITHOUT ANY WARRANTY; without even the implied warranty of

MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU

General Public License for more details.

You should have received a copy of the GNU General Public License

along with this program; if not, write to the Free Software

Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

// vim: set syntax=asciidoc: