diff --git a/Automation/Modules/Render/render.asciidoc b/Automation/Modules/Render/render.asciidoc old mode 100644 new mode 100755 index f7ca5fd..715b7b9 --- a/Automation/Modules/Render/render.asciidoc +++ b/Automation/Modules/Render/render.asciidoc @@ -7,11 +7,291 @@ render - Standardize production tasks. Synopsis -------- -centos-art.sh render [OPTIONS] DIRECTORY ... +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 --------------