centos-art.sh(1)

================

Name

----

centos-art.sh - The CentOS artwork repository automation tool.

Synopsis

--------

*centos-art.sh* [*--help*|*--version*]::

    Print information about *centos-art.sh* script itself.

*centos-art.sh* *MODULE* [*--help|--version*]::

    Print information about the specified module. See <<modules>>

    below to see which modules are available inside the

    *centos-art.sh* script.

Description

-----------

*centos-art.sh* exists to standardize frequent tasks inside the CentOS

repository.

When you execute the *centos-art.sh* script in a terminal, it will

request the absolute path where you stored your working copy of CentOS

artwork repository.  To avoid the absolute path request every time you

execute the script, you can edit the +~/.bash_profile+ file and

declare the absolute path to your working copy there, as value to

TCAR_BASEDIR variable.

Once *centos-art.sh* script knows what the absolute path to your

working copy is, it executes the file *centos-art.conf* to load

default values to configuration variables into its execution

environment.  After configuration variables have been loaded in the

execution environment, the script looks for supported options in the

first argument. If the options passed are recognized the script

process them. If the options aren't recognized or no option is passed

at all, the *centos-art.sh* script exports common functions and

executes the module specified as first argument, assuming the first

argument is a valid module name of course.  Finally, the

*centos-art.sh* script waits for the module environment to conclude

their job and exits, as described in <<exit-status>>.

[[exit-status]]

Exit Status

-----------

 * 0 -- Exit successfully without errors.

 * 1 -- Exit with errors.

[[modules]]

Modules

-------

From version 0.5, the *centos-art.sh* script was redesigned to

introduce the idea of modules to its base design. Modules are

individual execution environments that may nest themselves one inside

another efficiently to achieve high levels maintainability and

extensibility.  This make possible for modules to divide big tasks

into smaller tasks that can be easier to debug, maintain and share

with other modules efficiently (e.g., instead of loading modules all

at once, they are only loaded at demand and unset once they conclude

their execution).

The following modules are available from the *centos-art.sh* script

command-line:

*prepare*::

    This module standardizes configuration tasks needed by your

    working copy (e.g., verify whether required packages are installed

    or not in your workstation, calls render module to produce images

    and manuals in the correct order). This is the first task you

    should run in your workstation, just after downloading a fresh

    working copy of CentOS artwork repository.

*render*::

    This module standardizes the way content is produced inside the

    repository. This function relies on configuration files to do its

    work. Whenever you need to produce images, documentation or

    localized content this is the module you'll need to use.

*locale*::

    This module standardizes the way translatable strings are

    retrieved from source files and put into portable objects for you

    to edit.  Portable objects produced by this module are used by

    *render* module to produce localized content.  Whenever you need

    to produce the intermediate files holding the translatable strings

    required to produce localized content, use this module.

*help*::

    This module standardizes they way module's documentation is

    retrieved from their respective locations inside the repository.

    Use this module whenever you need help about the *centos-art.sh*

    script and its modules.

*tuneup*::

    This module standardizes maintenance tasks frequently run inside

    the repository.

*pack*::

    *Not implemented, yet.* This module standardizes the way RPM

    packages are produced from content available in the repository.

    When ever you need to produce RPM packages with information

    available in the repository, use this module.

Directory Structure

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

Inside the repository, modules related to *centos-art.sh* script are

stored in the directory +Automation/Modules/${MODULE_NAME}/+.

*Modules/*::

    This directory contains module's modules.

*Manuals/*::

    This directory contains module's documentation produced by *help*

    module.  The structure of this directory looks as follow:

+

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

Manuals/

|-- ${LANG}/

|   |-- man${SECTION_NUMBER}

|   `-- ${MODULE_NAME}.${SECTION_NUMBER}

`-- man${SECTION_NUMBER}

    `-- ${MODULE_NAME}.${SECTION_NUMBER}

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

*Locales/*::

    This directory contains module's translations produced by *locale*

    module. The structure of this directory looks as follow:

+

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

Locales/

`-- ${LANG}/

    |-- LC_MESSAGES

    |   |-- ${MODULE_NAME}.sh.mo

    |   `-- ${MODULE_NAME}.docbook.mo

    |-- ${MODULE_NAME}.sh.po

    |-- ${MODULE_NAME}.sh.pot

    |-- ${MODULE_NAME}.docbook.po

    `-- ${MODULE_NAME}.docbook.pot

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

*Scripts/*::

    This directory contains function scripts written by module's

    writers. Here is where all the tasks the module is useful for are

    written and stored in.  As convention the following structure is

    used:

+

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

Scripts/

`-- ${MODULE_NAME}_${FUNCTION_NAME}.sh

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

+

{asccidoc-br}

+

Inside each function script, there is a top comment where you should

put the name of the function script, a brief description about what it

does, as well as author and copying information. After the top comment

and separated by one white line, you should define the function

sentence using the long format.

+

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

#!/bin/bash

######################################################################

#

#   ${MODULE_NAME}_${FUNCTION_NAME}.sh -- ${FUNCTION_DESCRIPTION}

#

#   Written by:

#   * ${AUTHOR_NAME} <${AUTHOR_EMAIL}>, ${YEARS}

#

# Copyright (C) ${YEAR} 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.

#

######################################################################

function ${MODULE_NAME}_${FUNCTION_NAME} {

    ...

}

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

+

[NOTE]

If your are planning to contribute a new module to *centos-art.sh*

script, please, consider using the layout described above for all your

function scripts, consistently.

*$\{MODULE_NAME}.asciidoc*::

    This file contains the module's documentation source. From this

    file it is possible to produce the same documentation in other

    formats including manpage, html and pdf. Whenever you need to

    improve the module's documentation, edit this file.

*$\{MODULE_NAME}.conf*::

    This file contains the module's configuration variables. These

    variables are exported to the environment and remain there as long

    as the script execution environment is alive. Some variables are

    read-only others not.

+

The configuration file provides explanation about each environment

variable it exports. If you want to know more about what these

variables are, open this file and read the comments near each

variable.

*$\{MODULE_NAME}.sh*::

    This is the module's initialization script. The first file

    executed when the module called from the command-line. This file

    provides access to argument parsing and controls how

    module-specific function scripts are called. This is the starting

    point for writing modules. You can write a complete module using

    this file only but, frequently, it is convenient as the module

    complexity grows to divide it in smaller pieces (function scripts)

    to improve maintainability and error findings.

Options

-------

*--help*::

    Print script documentation.

*--version*::

    Print script version.

Bugs

----

The *pack* module isn't implemented yet.

Reporting Bugs

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

Report bugs inside the *automation* category of *centos-artwork*

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

Author

------

The *centos-art.sh* script has received contribution from the

following people:

 * Alain Reguera Delgado <mailto:al@centos.org.cu[al@centos.org.cu]>, 2009-2013

Copyright

---------

Copyright (C) 2009-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: