From 5da4a886984a656e8da2d55e57f93ee908a5bc92 Mon Sep 17 00:00:00 2001 From: Alain Reguera Delgado Date: Apr 03 2011 19:06:56 +0000 Subject: Update repository documentation manual. --- diff --git a/Identity/Manual/Directories/trunk/Scripts/Functions/Prepare.texi b/Identity/Manual/Directories/trunk/Scripts/Functions/Prepare.texi index ca4d1c5..f95e79c 100644 --- a/Identity/Manual/Directories/trunk/Scripts/Functions/Prepare.texi +++ b/Identity/Manual/Directories/trunk/Scripts/Functions/Prepare.texi @@ -1,10 +1,10 @@ @subsection Goals This section exists to organize files related to @file{centos-art.sh} -script @samp{verify} functionality. The @samp{verify} -functionality of @file{centos-art.sh} script helps you to verify the -workstation configuration you are planning to use as host for your -working copy of CentOS Artwork Repository. +script @samp{prepare} functionality. The @samp{prepare} functionality +of @file{centos-art.sh} script helps you to prepare the workstation +configuration you are planning to use as host for your working copy of +CentOS Artwork Repository. @subsection Description @@ -12,12 +12,12 @@ The first time you download CentOS Artwork Repository you need to configure your workstation in order to use @file{centos-art.sh} script. These preliminar configurations are based mainly on auxiliar RPM packages installation, symbolic links creations, and environment -variables definitions. The @samp{verify} functionality of +variables definitions. The @samp{prepare} functionality of @file{centos-art.sh} script guides you through this preliminar configuration process. If this is the first time you run @file{centos-art.sh} script, the -appropriate way to use its @samp{verify} functionality is not using +appropriate way to use its @samp{prepare} functionality is not using the @file{centos-art.sh} script directly, but the absolute path to @command{centos-art.sh} script instead (i.e., @file{~/artwork/trunk/Scripts/Bash/centos-art.sh}). This is necessary @@ -49,7 +49,7 @@ installation functionality. If your user isn't defined as a privileged user---at least to run @command{yum} commands--- inside @file{/etc/sudoers} configuration file, you will not be able to perform package installation tasks as set in @file{centos-art.sh} -script @samp{verify} functionality. +script @samp{prepare} functionality. Setting sudo privileges to users is an administrative task you have to do by yourself. If you don't have experience with @command{sudo} @@ -96,10 +96,10 @@ cannot be branched under @file{branches/Scripts} directory structure. Definition of environemnt variables helps us to set default values to our user session life. The user session environment variable defintion takes place in the user's @file{~/.bash_profile} file. The -@samp{verify} functionality of @file{centos-art.sh} script doesn't +@samp{prepare} functionality of @file{centos-art.sh} script doesn't modify your @file{~/.bash_profile} file. -The @samp{verify} functionality of @file{centos-art.sh} script +The @samp{prepare} functionality of @file{centos-art.sh} script evaluates the following environment variables: @table @env @@ -184,11 +184,210 @@ The format of @var{TZ} environment variable is described in @end table +@subsubsection Shell Script Files + +The @code{shell} functionality of @file{centos-art.sh} script helps +you to maintain bash scripts inside repository. For example, suppose +you've created many functionalities for @file{centos-art.sh} script, +and you want to use a common copyright and license note for +consistency in all your script files. If you have a bunch of files, +doing this one by one wouldn't be a big deal. In contrast, if the +amount of files grows, updating the copyright and license note for all +of them would be a task rather tedious. The @code{shell} functionality +exists to solve maintainance tasks just as the one previously +mentioned. + +When you use @code{shell} functionality to update copyright inside +script files, it is required that your script files contain (at least) +the following top commentary structure: + +@verbatim + 1| #!/bin/bash + 2| # + 3| # doSomething.sh -- The function description goes here. + 4| # + 5| # Copyright + 6| # + 7| # ... + 8| # + 9| # ---------------------------------------------------------------------- +10| # $Id$ +11| # ---------------------------------------------------------------------- +12| +13| function doSomething { +14| +15| } +@end verbatim + +Relevant lines in the above structure are lines from 5 to 9. +Everything else in the file is left immutable. + +When you are updating copyright through @code{shell} +functionality, the @file{centos-art.sh} script replaces everything +in-between line 5 ---the first one matching @samp{^# Copyright .+$} +string--- and line 9---the first long dash separator matching @samp{^# +-+$}--- with the content of copyright template instance. + +@quotation +@strong{Caution} Be sure to add the long dash separator that matches +@samp{^# -+$} regular expression @emph{before} the function +definition. Otherwise, if the @samp{Copyright} line is present but no +long dash separator exists, @file{centos-art.sh} will remove anything +in-between the @samp{Copyright} line and the end of file. This way you +may lost your function definitions entirely. +@end quotation + +The copyright template instance is created from one copyright template +stored in the @file{Config/tpl_forCopyright.sed} file. The template +instance is created once, and later removed when no longer needed. At +this moment, when template instance is created, the +@file{centos-art.sh} script takes advantage of automation in order to +set copyright full name and date dynamically. + +When you use @code{shell} functionality to update copyright, the first +thing @file{shell} functionality does is requesting copyright +information to user, and later, if values were left empty (i.e., no +value was typed before pressing @key{RET} key), the @file{shell} +functionality uses its own default values. + +When @code{shell} functionality uses its own default values, the final +copyright note looks like the following: + +@verbatim + 1| #!/bin/bash + 2| # + 3| # doSomthing.sh -- The function description goes here. + 4| # + 5| # Copyright (C) 2003, 2010 The CentOS Project + 6| # + 7| # This program is free software; you can redistribute it and/or modify + 8| # it under the terms of the GNU General Public License as published by + 9| # the Free Software Foundation; either version 2 of the License, or +10| # (at your option) any later version. +11| # +12| # This program is distributed in the hope that it will be useful, but +13| # WITHOUT ANY WARRANTY; without even the implied warranty of +14| # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +15| # General Public License for more details. +16| # +17| # You should have received a copy of the GNU General Public License +18| # along with this program; if not, write to the Free Software +19| # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 +20| # USA. +21| # +22| # ---------------------------------------------------------------------- +23| # $Id$ +24| # ---------------------------------------------------------------------- +25| +26| function doSomething { +27| +28| } +@end verbatim + +Relevant lines in the above structure are lines from 5 to 22. Pay +attention how the copyright line was built, and how the license was +added into the top comment where previously was just three dots. +Everything else in the file was left immutable. + +To change copyright information (i.e., full name or year information), +run the @code{shell} functionality over the root directory containing +the script files you want to update copyright in and enter the +appropriate information when it be requested. You can run the +@code{shell} functionality as many times as you need to. + +To change copyright license (i.e., the text in-between lines 7 and +20), you need to edit the @file{Config/tpl_forCopyright.sed} file, set +the appropriate information, and run the @code{shell} functionality +once again for changes to take effect over the files you specify. + +@quotation +@strong{Important} The @file{centos-art.sh} script is released as: + +@verbatim +GNU GENERAL PUBLIC LICENSE +Version 2, June 1991 + +Copyright (C) 1989, 1991 Free Software Foundation, Inc. +59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. +@end verbatim + +Do not change the license information under which @file{centos-art.sh} +script is released. Instead, if you think a different license must be +used, please share your reasons at @email{centos-devel@@centos-art.sh, +CentOS Developers mailing list}. + +See file +@url{file:///home/centos/artwork/trunk/Scripts/COPYING,trunk/Scripts/COPYING}, +for a complete license description. +@end quotation + +@subsubsection SVG Files + +The @code{svg} functionality of @file{centos-art.sh} script helps you +to maintain scalable vector graphics (SVG) inside repository. For +example, suppose you've been working in CentOS default design models +under @file{trunk/Identity/Themes/Models/}, and you want to set common +metadata to all of them, and later remove all unused SVG defintions +from @samp{*.svg} files. Doing so file by file may be a tedious task, +so the @file{centos-art.sh} script provides the @code{svg} +functionality to aid you maintain such actions. + +The metadata used is defined by Inkscape 0.46 using the SVG standard +markup. The @file{centos-art.sh} script replaces everything +in-between @code{} tags with a +predefined metadata template we've set for this purpose. + +The metadata template was created using the metadata information of a +file which, using Inkscape 0.46, all metadata fields were set. This +created a complete markup representation of how SVG metadata would +look like. Later, we replaced every single static value with a +translation marker in the form @samp{=SOMETEXT=}, where +@code{SOMETEXT} is the name of its main opening tag. Later, we +transform the metadata template into a sed replacement set of commads +escaping new lines at the end of each line. + +With metadata template in place, the @file{centos-art.sh} script uses +it to create a metadata template instance for the file being processed +currently. The metadata template instance contains the metadata +portion of sed replacement commands with translation markers already +traduced. In this action, instance creation, is where we take +advantage of automation and generate metadata values like title, date, +keywords, source, identifier, and relation dynamically, based on the +file path @file{centos-art.sh} script is currently creating metadata +information for. + +With metadata template instance in place, the @file{centos-art.sh} +script uses it to replace real values inside all @samp{.svg} files +under the current location you're running the @file{centos-art.sh} +script on. Default behaviour is to ask user to enter each metadatum +required, one by one. If user leaves metadatum empty, by pressing +@key{RET} key, @file{centos-art.sh} uses its default value. + +Many of the no-longer-used gradients, patterns, and markers (more +precisely, those which you edited manually) remain in the +corresponding palettes and can be reused for new objects. However if +you want to optimize your document, use the @samp{Vacuum Defs} command +in @samp{File} menu. It will remove any gradients, patterns, or +markers which are not used by anything in the document, making the +file smaller. + +If you have one or two couple of files, removing unused definitions +using the graphical interface may be enough to you. In contrast, if +you have dozens or even houndreds of scalable vector graphics files to +maintain it is not a fun task to use the graphical interface to remove +unused definitions editing those files one by one. + +To remove unused definitions from several scalable vector graphics +files, the @file{centos-art.sh} script uses Inkscape command-line +interface, specifically with the @option{--vaccum-defs} option. + +@subsubsection XHTML Files + @subsection Usage @table @command -@item centos-art verify --packages +@item centos-art prepare --packages Verify required packages your workstation needs in order to run the @file{centos-art.sh} script correctly. If there are missing packages, @@ -201,7 +400,7 @@ In case all packages required by @file{centos-art.sh} script are already installed in your workstation, the message @samp{The required packages are already installed.} is output for you to know. -@item centos-art verify --links +@item centos-art prepare --links Verify required links your workstation needs in order to run the centos-art command correctly. If any required link is missing, the @@ -223,8 +422,8 @@ link. To end this continue request you can answer @samp{No}, or remove the existent regular file to let @file{centos-art.sh} script install the link on its place. -@item centos-art verify --environment -@itemx centos-art verify --environment --filter='regex' +@item centos-art prepare --environment +@itemx centos-art prepare --environment --filter='regex' Output a brief description of environment variables used by @file{centos-art.sh} script. @@ -241,5 +440,5 @@ provided at all. @menu * Directories trunk Scripts:: -@comment --- Removed(* Directories trunk Scripts Functions::) --- +* Directories trunk Scripts Functions:: @end menu