From 954d9457ba6da988be7fd454fb298a53f0eef8cc Mon Sep 17 00:00:00 2001 From: Alain Reguera Delgado Date: Jul 14 2013 04:38:24 +0000 Subject: Update centos-art.sh script. - Update initialization, configuration and documentation files. --- diff --git a/Automation/centos-art.asciidoc b/Automation/centos-art.asciidoc index 2354d12..2d87c6e 100644 --- a/Automation/centos-art.asciidoc +++ b/Automation/centos-art.asciidoc @@ -1,14 +1,274 @@ centos-art.sh(1) ================ -NAME +Name ---- centos-art.sh - The CentOS artwork repository automation tool -SYNOPSIS +Synopsis -------- -... +*centos-art.sh* [*--help*|*--version*]:: + This command provides information about the script itself. -DESCRIPTION +*centos-art.sh* *MODULE* [*--help|--version*]:: + This command provides information about the specified module. See + the xref:Modules[] section below to see which modules are + available. + +*centos-art.sh* *MODULE* [*OPTIONS*]:: + This command executes the specified module. Options here are + module-specific. See the xref:Modules[] section below to see which + modules are available. + +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 set +the absolute path to your working copy there, as value to +TCAR_BASEDIR variable. + +Once *centos-art.sh* script knows what is the absolute path to your +working copy, 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 whether or not any option was passed as +first argument to *centos-art.sh* script. If no option was passed, it +gives control to *cli* module. At this point, the *centos-art.sh* +script waits for modules to conclude their job and exit the script +execution as described in the xref:exit[] section. + +anchor:exit[Exit Status] + +Exit Status +----------- + * 0 -- Exit successfully without errors. + * 1 -- Exit with errors. + +anchor:Modules[Modules] + +Modules +------- +From version 0.5 on, *centos-art.sh* script introduces the idea of +modules to its base design. Modules are individual execution +environments that may nest themselves one inside another to achieve +high levels of code maintainability. Modules make it possible to +divide a big task into smaller tasks that can be easier to debug, +maintain and share with other modules. + +The following modules are available for *centos-art.sh* script: + +*cli*:: + This modules initializes common and specific functions inside + *centos-art.sh* script execution environment. This module is + loaded internally when you execute the *centos-art.sh* script in a + terminal and you probably don't need to execute it in a terminal + unless you want to see help or version information about it. This + module interprets arguments passed to *centos-art.sh* command-line + to execute the associated module (a.k.a., specific functions). + +*prepare*:: + This module standardizes configuration tasks needed by your + working copy (e.g., creation of links, images and documentations). + 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. 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 the way documentation is produced inside + the repository. Whenever you need to manage documentation source + files inside the repository, use this module. + +*tuneup*:: + This module standardizes maintenance tasks frequently run inside + the repository. + +*vcs*:: + This module standardizes the way version control tasks are + performed inside the repository. This module is used internally + and you probably don't need to use it from the command line. This + module is the interface that let us support different version + control systems inside *centos-art.sh* script. + +*pack*:: + 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+. + +*Modules/*:: + This directory contains module's modules. +*Manuals/*:: + This directory contains module's documentation in manpage format. + The structure of this directory is as follows: ++ +------------------------------------- +Manuals/ +|-- ${LANG}/ +| |-- man${SECTION_NUMBER} +| `-- ${MODULE_NAME}.${SECTION_NUMBER} +`-- man${SECTION_NUMBER} + `-- ${MODULE_NAME}.${SECTION_NUMBER} +------------------------------------- + +*Locales/*:: + This directory contains module's translations using GNU gettext + standards. The structure of this directory is as follows: ++ +------------------------------------- +Locales/ +`-- ${LANG}/ + |-- LC_MESSAGES + | `-- ${MODULE_NAME}.sh.mo + |-- ${MODULE_NAME}.sh.po + |-- ${MODULE_NAME}.sh.pot + |-- ${MODULE_NAME}.xml.po + `-- ${MODULE_NAME}.xml.pot +------------------------------------- + +*Scripts/*:: + This directory contains module's function scripts. Here is where + all the tasks the module is useful to are written and organized. + 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. +*$\{MODULE_NAME}.xml*:: + This file is produced from *$\{MODULE_NAME}.asciidoc* and is used as + source to retrieve translatable strings. Translatable strings + retrieved from this file are stored in the module's *Locales/* + directory and used to produce localized mapages inside module's + *Manuals/$\{LANG}/man$\{SECTION_NUMBER}/* directory. + +Options +------- + +*--help*:: + Display program's help (this page). + +*--version*:: + Display program's name and version. + +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: diff --git a/Automation/centos-art.conf b/Automation/centos-art.conf index f2c507b..0a3a19e 100755 --- a/Automation/centos-art.conf +++ b/Automation/centos-art.conf @@ -1,10 +1,10 @@ #!/bin/bash -######################################################################## +###################################################################### # # centos-art.conf -- This file provides default configuration values # to centos-art.sh script. # -# Written by: +# Written by: # * Alain Reguera Delgado , 2013 # Key fingerprint = D67D 0F82 4CBD 90BC 6421 DF28 7CCE 757C 17CA 3951 # @@ -24,34 +24,111 @@ # along with this program; if not, write to the Free Software # Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. # -######################################################################## +###################################################################### -# ---------------------------------------------------------------------- +# -------------------------------------------------------------------- +# Script's identity configuration variables. +# -------------------------------------------------------------------- +# +# Set the script name. +# +declare -x TCAR_SCRIPT_NAME="centos-art.sh" +# +# Set the script command name. +# +declare -x TCAR_SCRIPT_COMMAND="centos-art" +# +# Set the script version. +# +declare -x TCAR_SCRIPT_VERSION='0.5' + +# -------------------------------------------------------------------- # Command-line interface (read-only) configuration variables. -# ---------------------------------------------------------------------- -declare -xr TCAR_CLI_NAME="centos-art.sh" -declare -xr TCAR_CLI_COMMAND="centos-art" -declare -xr TCAR_CLI_VERSION='0.5' -declare -xr TCAR_CLI_LANG_LC=$(echo ${LANG} | cut -d'.' -f1) -declare -xr TCAR_CLI_LANG_LL=$(echo ${TCAR_CLI_LANG_LC} | cut -d'_' -f1) -declare -xr TCAR_CLI_LANG_CC=$(echo ${TCAR_CLI_LANG_LC} | cut -d'_' -f2) -declare -xr TCAR_CLI_INIT=cli -declare -xr TCAR_CLI_INIT_DIR=${TCAR_CLI_BASEDIR}/Modules/${TCAR_CLI_NAME}-${TCAR_CLI_INIT} -declare -xr TCAR_CLI_INIT_FILE=${TCAR_CLI_INIT_DIR}/${TCAR_CLI_INIT}.sh -declare -xr TCAR_CLI_TEMPDIR=$(mktemp -p /tmp -d ${TCAR_CLI_NAME}-XXXXXX) +# -------------------------------------------------------------------- +# +# Set the script initialization module's name. +# +declare -xr TCAR_SCRIPT_INIT=cli +# +# Set the script initialization module's directory. +# +declare -xr TCAR_SCRIPT_INIT_DIR=${TCAR_SCRIPT_BASEDIR}/Modules/${TCAR_SCRIPT_NAME}-${TCAR_SCRIPT_INIT} +# +# Set the script initialization module's file. +# +declare -xr TCAR_SCRIPT_INIT_FILE=${TCAR_SCRIPT_INIT_DIR}/${TCAR_SCRIPT_INIT}.sh +# +# Set the script temporal directory. +# +declare -xr TCAR_SCRIPT_TEMPDIR=$(mktemp -p /tmp -d ${TCAR_SCRIPT_NAME}-XXXXXX) -# ---------------------------------------------------------------------- +# -------------------------------------------------------------------- +# Internationalization configuration variables and functions. +# -------------------------------------------------------------------- +# +# Set the script language information using the LC format. This format +# shows both language and country information (e.g., `es_ES'). +# +declare -xr TCAR_SCRIPT_LANG_LC=$(echo ${LANG} | cut -d'.' -f1) +# +# Set the script language information using the LL format. This format +# shows only the language information (e.g., `es'). +# +declare -xr TCAR_SCRIPT_LANG_LL=$(echo ${TCAR_SCRIPT_LANG_LC} | cut -d'_' -f1) +# +# Set the script language information using the CC format. This format +# shows only the country information (e.g., `ES'). +# +declare -xr TCAR_SCRIPT_LANG_CC=$(echo ${TCAR_SCRIPT_LANG_LC} | cut -d'_' -f2) +# +# Set function environments required by GNU gettext system. +# +. gettext.sh +# +# Set the script text domain. This information is used by gettext +# system to retrieve translated strings from machine object (MO) files +# with this name. This variable is reset each time a new module is +# loaded, so the correct files can be used. +# +declare -x TEXTDOMAIN=${TCAR_SCRIPT_NAME} +# +# Set the script text domain directory. This information is used by +# gettext system to know where the machine objects are stored in. This +# variable is reset each time a new module is loaded, so the correct +# files can be used. +# +declare -x TEXTDOMAINDIR=${TCAR_SCRIPT_BASEDIR}/Locales + +# -------------------------------------------------------------------- # Module-specific configuration variables. -# ---------------------------------------------------------------------- +# -------------------------------------------------------------------- # # This variable is used in different function environments to pass # positional parameters from one environment to another using local # definitions. -declare -x TCAR_MODULE_ARGUMENTS='' +# +declare -x TCAR_ARGUMENTS='' +# +# Set absolute path to documentation source format. This is the file +# we'll use as input to `a2x' command to produce documentation in +# different formats. +# +declare -x TCAR_MANUAL_FILE=${TCAR_SCRIPT_BASEDIR}/${TCAR_SCRIPT_NAME}.asciidoc +# +# Set absolute path to documentation search path. This is the location +# where final documentation formats (e.g., man pages) will be saved +# in. +# +declare -x TCAR_MANUAL_SEARCHPATH=${TCAR_SCRIPT_BASEDIR}/Manuals +# +# Set command used to read man pages. Include in this command the +# sarch path where final man pages live in. +# +declare -x TCAR_MANUAL_READER="/usr/bin/man -M ${TCAR_MANUAL_SEARCHPATH}" -# ---------------------------------------------------------------------- +# -------------------------------------------------------------------- # User-related configuration variables. -# ---------------------------------------------------------------------- +# -------------------------------------------------------------------- # # Set file path to your preferred text editor. The editor you specify # will be use when you need to write commit messages and anything that @@ -67,9 +144,9 @@ declare -x TCAR_USER_EDITOR=/bin/vi # declare -xr TCAR_USER_CONFIG=${HOME}/.centos-art.conf -# ---------------------------------------------------------------------- +# -------------------------------------------------------------------- # Flag-related configuration variables. -# ---------------------------------------------------------------------- +# -------------------------------------------------------------------- # # Set filter flag (-f|--filter). This flag is mainly used to reduce # the number of files to process and is interpreted as egrep-posix diff --git a/Automation/centos-art.sh b/Automation/centos-art.sh index fd3a702..cd68a15 100755 --- a/Automation/centos-art.sh +++ b/Automation/centos-art.sh @@ -27,32 +27,55 @@ # Verify absolute path to the working directory. This information is # critical for centos-art.sh script to work. -if [[ ! ${TCAR_REPO_WRKDIR} ]] || [[ -z ${TCAR_REPO_WRKDIR} ]] \ - || [[ ! -d ${TCAR_REPO_WRKDIR} ]];then - if [[ ! -d $(dirname ${0}) ]] || [[ $(dirname ${0}) =~ "^${HOME}/bin" ]];then - printf "Enter repository's absolute path:" - read TCAR_REPO_WRKDIR - fi +if [[ ! ${TCAR_BASEDIR} ]] || [[ -z ${TCAR_BASEDIR} ]] \ + || [[ ! -d ${TCAR_BASEDIR} ]];then + echo -n "Enter repository's absolute path: " + read TCAR_BASEDIR fi # Define automation scripts base directory. We need to define it here # in order to reach the configuration file. All other environment # variable definitions must be declared inside the configuration file. -declare -xr TCAR_CLI_BASEDIR=${TCAR_REPO_WRKDIR}/Automation +if [[ -d ${TCAR_BASEDIR} ]];then + declare -xr TCAR_SCRIPT_BASEDIR=${TCAR_BASEDIR}/Automation +else + exit 1 +fi # Initialize default configuration values. -. ${TCAR_CLI_BASEDIR}/centos-art.conf +if [[ -d ${TCAR_SCRIPT_BASEDIR} ]];then + . ${TCAR_SCRIPT_BASEDIR}/centos-art.conf +else + exit 1 +fi # Initialize user-specific configuration values. if [[ -f ${TCAR_USER_CONFIG} ]];then . ${TCAR_USER_CONFIG} fi -# Initialize the centos-art.sh script command-line interface. -if [[ -x ${TCAR_CLI_INIT_FILE} ]];then - . ${TCAR_CLI_INIT_FILE} \ - && export -f ${TCAR_CLI_INIT} \ - && ${TCAR_CLI_INIT} "$@" -else - echo "${TCAR_CLI_INIT_FILE} has not execution rights." -fi +case ${1} in + + --help ) + # Print script help. + ${TCAR_MANUAL_READER} ${TCAR_SCRIPT_NAME} + ;; + + --version ) + # Print script version. + echo "`eval_gettext "Running $TCAR_SCRIPT_NAME (v$TCAR_SCRIPT_VERSION)."`" + ;; + + * ) + # Initialize script command-line interface. + if [[ -x ${TCAR_SCRIPT_INIT_FILE} ]];then + . ${TCAR_SCRIPT_INIT_FILE} \ + && export -f ${TCAR_SCRIPT_INIT} \ + && ${TCAR_SCRIPT_INIT} "$@" + else + echo "${TCAR_SCRIPT_INIT_FILE} `gettext "has not execution rights."`" + fi + ;; +esac + +exit 0