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: