Blame Identity/Manual/Directories/trunk/Scripts/Functions/Shell.texi

9c6e0d
@subsection Goals
9c6e0d
9c6e0d
This section exists to organize files related to @code{shell}
9c6e0d
functionality of @file{centos-art.sh} script.
9c6e0d
9c6e0d
@subsection Description
9c6e0d
9c6e0d
The @code{shell} functionality of @file{centos-art.sh} script helps
9c6e0d
you to maintain bash scripts inside repository. For example, suppose
9c6e0d
you've created many functionalities for @file{centos-art.sh} script,
9c6e0d
and you want to use a common copyright and license note for
9c6e0d
consistency in all your script files. If you have a bunch of files,
9c6e0d
doing this one by one wouldn't be a big deal. In contrast, if the
9c6e0d
amount of files grows, updating the copyright and license note for all
9c6e0d
of them would be a task rather tedious. The @code{shell} functionality
9c6e0d
exists to solve maintainance tasks just as the one previously
9c6e0d
mentioned.
9c6e0d
9c6e0d
When you use @code{shell} functionality to update copyright inside
9c6e0d
script files, it is required that your script files contain (at least)
9c6e0d
the following top commentary structure:
9c6e0d
9c6e0d
@float Figure,fig:trunk/Scripts/Bash/Functions/Shell:1
9c6e0d
@verbatim
9c6e0d
 1| #!/bin/bash
9c6e0d
 2| #
9c6e0d
 3| # doSomething.sh -- The function description goes here.
9c6e0d
 4| # 
9c6e0d
 5| # Copyright
9c6e0d
 6| #
9c6e0d
 7| # ...
9c6e0d
 8| #
9c6e0d
 9| # ----------------------------------------------------------------------
9c6e0d
10| # $Id$
9c6e0d
11| # ----------------------------------------------------------------------
9c6e0d
12|
9c6e0d
13| function doSomething {
9c6e0d
14|     
9c6e0d
15| }
9c6e0d
@end verbatim
9c6e0d
@caption{The functions script base comment structure}
9c6e0d
@end float
9c6e0d
9c6e0d
Relevant lines in the above structure are lines from 5 to 9.
9c6e0d
Everything else in the file is left immutable.
9c6e0d
9c6e0d
When you are updating copyright through @code{shell}
9c6e0d
functionality,  the @file{centos-art.sh} script replaces everything
9c6e0d
in-between line 5 ---the first one matching @samp{^# Copyright .+$}
9c6e0d
string--- and line 9---the first long dash separator matching @samp{^#
9c6e0d
-+$}--- with the content of copyright template instance.
9c6e0d
9c6e0d
@quotation
9c6e0d
@strong{Caution} Be sure to add the long dash separator that matches
9c6e0d
@samp{^# -+$} regular expression @emph{before} the function
9c6e0d
definition. Otherwise, if the @samp{Copyright} line is present but no
9c6e0d
long dash separator exists, @file{centos-art.sh} will remove anything
9c6e0d
in-between the @samp{Copyright} line and the end of file. This way you
9c6e0d
may lost your function definitions entirely.
9c6e0d
@end quotation
9c6e0d
9c6e0d
The copyright template instance is created from one copyright template
9c6e0d
stored in the @file{Config/tpl_forCopyright.sed} file.  The template
9c6e0d
instance is created once, and later removed when no longer needed. At
9c6e0d
this moment, when template instance is created, the
9c6e0d
@file{centos-art.sh} script takes advantage of automation in order to
9c6e0d
set copyright full name and date dynamically.
9c6e0d
9c6e0d
When you use @code{shell} functionality to update copyright, the first
9c6e0d
thing @file{shell} functionality does is requesting copyright
9c6e0d
information to user, and later, if values were left empty (i.e., no
9c6e0d
value was typed before pressing @key{RET} key), the @file{shell}
9c6e0d
functionality uses its own default values.
9c6e0d
9c6e0d
When @code{shell} functionality uses its own default values, the final
9c6e0d
copyright note looks like the following:
9c6e0d
9c6e0d
@float Figure,fig:trunk/Scripts/Bash/Functions/Shell:2
9c6e0d
@verbatim
9c6e0d
 1| #!/bin/bash
9c6e0d
 2| #
9c6e0d
 3| # doSomthing.sh -- The function description goes here.
9c6e0d
 4| #
9c6e0d
 5| # Copyright (C) 2003, 2010 The CentOS Project
9c6e0d
 6| # 
9c6e0d
 7| # This program is free software; you can redistribute it and/or modify
9c6e0d
 8| # it under the terms of the GNU General Public License as published by
9c6e0d
 9| # the Free Software Foundation; either version 2 of the License, or
9c6e0d
10| # (at your option) any later version.
9c6e0d
11| # 
9c6e0d
12| # This program is distributed in the hope that it will be useful, but
9c6e0d
13| # WITHOUT ANY WARRANTY; without even the implied warranty of
9c6e0d
14| # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
9c6e0d
15| # General Public License for more details.
9c6e0d
16| #
9c6e0d
17| # You should have received a copy of the GNU General Public License
9c6e0d
18| # along with this program; if not, write to the Free Software
9c6e0d
19| # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
9c6e0d
20| # USA.
9c6e0d
21| #
9c6e0d
22| # ----------------------------------------------------------------------
9c6e0d
23| # $Id$
9c6e0d
24| # ----------------------------------------------------------------------
9c6e0d
25|
9c6e0d
26| function doSomething {
9c6e0d
27|
9c6e0d
28| }
9c6e0d
@end verbatim
9c6e0d
@caption{The function script comment example}
9c6e0d
@end float
9c6e0d
9c6e0d
Relevant lines in the above structure are lines from 5 to 22.  Pay
9c6e0d
attention how the copyright line was built, and how the license was
9c6e0d
added into the top comment where previously was just three dots.
9c6e0d
Everything else in the file was left immutable. 
9c6e0d
9c6e0d
To change copyright information (i.e., full name or year information),
9c6e0d
run the @code{shell} functionality over the root directory containing
9c6e0d
the script files you want to update copyright in and enter the
9c6e0d
appropriate information when it be requested. You can run the
9c6e0d
@code{shell} functionality as many times as you need to.
9c6e0d
9c6e0d
To change copyright license (i.e., the text in-between lines 7 and
9c6e0d
20), you need to edit the @file{Config/tpl_forCopyright.sed} file, set
9c6e0d
the appropriate information, and run the @code{shell} functionality
9c6e0d
once again for changes to take effect over the files you specify.
9c6e0d
9c6e0d
@quotation
9c6e0d
@strong{Important} The @file{centos-art.sh} script is released as: 
9c6e0d
9c6e0d
@verbatim
9c6e0d
GNU GENERAL PUBLIC LICENSE
9c6e0d
Version 2, June 1991
9c6e0d
9c6e0d
Copyright (C) 1989, 1991 Free Software Foundation, Inc.
9c6e0d
59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
9c6e0d
@end verbatim
9c6e0d
9c6e0d
Do not change the license information under which @file{centos-art.sh}
9c6e0d
script is released. Instead, if you think a different license must be
9c6e0d
used, please share your reasons at @email{centos-devel@@centos-art.sh,
9c6e0d
CentOS Developers mailing list}.
9c6e0d
@end quotation
9c6e0d
9c6e0d
@subsection Usage
9c6e0d
9c6e0d
@table @command
9c6e0d
@item centos-art sh --update-copyright='path/to/dir'
9c6e0d
@itemx centos-art sh --update-copyright='path/to/dir' --filter='regex'
9c6e0d
Use these commands to update copyright information in @samp{.sh} files
9c6e0d
under @samp{path/to/dir} directory. 
9c6e0d
@end table
9c6e0d
9c6e0d
When you provide @option{--filter='regex'} argument, the list of files
9c6e0d
to process is reduced as specified in @samp{regex} regular expression.
9c6e0d
Inside @file{centos-art.sh} script, the @samp{regex} regular
9c6e0d
expression is used in combination with @command{find} command to look
9c6e0d
for files matching the regular expression path pattern.
9c6e0d
9c6e0d
@quotation
9c6e0d
@strong{Warning} In order for @samp{regex} regular expression to match
9c6e0d
a file, the @samp{regex} regular expresion must match the whole file
9c6e0d
path not just the file name. 
9c6e0d
@end quotation
9c6e0d
9c6e0d
For example, if you want to match all @file{render.conf.sh} files
9c6e0d
inside @file{path/to/dir}, use the @code{.+/render.conf} regular
9c6e0d
expression.  Later, @file{centos-art.sh} script uses this value inside
9c6e0d
@code{^$REGEX\.sh$} expression in order to build the final regular
9c6e0d
expression (i.e., @code{^.+/render.conf\.sh$}) that is evaluated
9c6e0d
against available file paths inside the list of files to process.
9c6e0d
9c6e0d
Exceptionally, when you provide @option{--filter='regex'} in the way
9c6e0d
that @samp{regex}, appended to @samp{path/to/dir/} (i.e.
9c6e0d
@samp{path/to/dir/regex}), matches a regular file; the
9c6e0d
@file{centos-art.sh} script uses the file matching as only file in the
9c6e0d
list of files to process. 
9c6e0d
9c6e0d
@subsection See also
9c6e0d
9c6e0d
@menu
ed9de5
* Directories trunk Scripts::
ed9de5
@comment --- Removed(* Directories trunk Scripts Functions::) ---
9c6e0d
@end menu