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:
