From 2e07265b71225271db6644e08f09021f74f54be9 Mon Sep 17 00:00:00 2001 From: Alain Reguera Delgado Date: Oct 03 2013 18:16:21 +0000 Subject: Update centos-art.sh.asciidoc. --- diff --git a/Automation/Manuals/centos-art.sh.asciidoc b/Automation/Manuals/centos-art.sh.asciidoc index e9716a4..8d0d30d 100644 --- a/Automation/Manuals/centos-art.sh.asciidoc +++ b/Automation/Manuals/centos-art.sh.asciidoc @@ -14,233 +14,96 @@ Synopsis *centos-art.sh* *MODULE* [*--help|--version*]:: Print information about the specified module. See <> - below to see which modules are available inside the - *centos-art.sh* script. + below to see which modules *centos-art.sh* script supports. 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 ------------ - - * 0 -- Exit successfully without errors. - * 1 -- Exit with errors. +artwork repository. Inside *centos-art.sh* script, frequent tasks are +organized inside modules. + +When you execute the *centos-art.sh* script in a terminal, it requests +you to enter the absolute path of CentOS artwork repository in your +workstation. This information is required in order for *centos-art.sh* +to know where the repository directory structure you want to work with +is stored in. Later, once *centos-art.sh* knows where your copy of +CentOS artwork repository is stored in, it initializes configuration +variables and global functions. At this point, it continues reading +the command-line arguments to retrieve the module's name, process +common options next to it, store module-specific options and initiates +the module's environment by executing the module's initialization +script, based on the module's name retrieved from the command-line. [[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: + +The *centos-art.sh* script supports the following modules: *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. + Standardize 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. + Standardize 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. + Standardize 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. *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. + Standardize maintenance tasks frequently run inside the repository + (e.g., reset written by, copyright and license information inside + shell script's top-comments; transform probably malformed HTML + documents into valid documents, and remove unused tags inside SVG + documents.). +[[options]] Options ------- +The *centos-art.sh* script supports the following options: + *--help*:: Print script documentation. *--version*:: Print script version. -Bugs ----- +*--debug*:: + Enable debugging messages. -The *pack* module isn't implemented yet. +*--quiet*:: + Run the script quietly. Only error messages are printed out. -Reporting Bugs --------------- +*--yes*:: + Answer ``yes'' to all ``yes or no'' questions. This option is + useful when you run *centos-art.sh* with the *--quiet* option. + +[[exit-status]] +Exit Status +----------- + +* 0 -- Exit successfully without errors. +* 1 -- Exit with errors. + +[[bugs]] +Bugs +---- -Report bugs inside the *automation* category of *centos-artwork* -project, at the https://centos.org.cu/bugs/[The CentOS Bugs] website. +* https://centos.org.cu/bugs/[https://centos.org.cu/bugs/] Author ------ @@ -248,12 +111,12 @@ Author The *centos-art.sh* script has received contribution from the following people: - * Alain Reguera Delgado , 2009-2013 +* Alain Reguera Delgado , 2009-2013 Copyright --------- -Copyright (C) 2009-2013 The CentOS Project +Copyright (C) 2009-2013 The CentOS Artwork SIG 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