@subheading Goals

This section describes the @code{tuneup} functionality of
@command{centos-art.sh} script and general examples about file
maintainance inside a working copy of CentOS Artwork Repository.

@subheading Description

The @code{tuneup} functionality of @command{centos-art.sh} script
provides the standard way of maintaining files inside your working
copy of CentOS Artwork Repository.

Tasks related to file maintainance are repetitive. You might find
yourself doing them time after time inside the working copy of CentOS
Artwork Repository. Some of these maintainance tasks are updating top
comments on shell scripts, creating table of contents for web pages,
updating metadata related to design models and remove unused
definitions on design models.

The maintainance tasks are associated to file extensions. This way,
the @code{tuneup} functionality know what maintainance tasks should be
applied to what files inside the working copy of CentOS Artwork
Repository. For example, when you execute the @code{tuneup}
functionality, it makes a list of files based on supported extensions
(e.g., @file{.sh}, @file{.svg} and @file{.xhtml}) and apply
maintainance tasks file by file accordingly to its file extension.

@subsubheading Maintaining @file{.sh} files

If shell scripts are found, the @code{tuneup} functionality reads a
comment template
(@file{trunk/Scripts/Functions/Prepare/Config/shell_topcomment.sed})
and applies it to the shell scripts, one by one. As result, all shell
scripts will end up having the same copyright and license information
the comment template does.

In order for the comment template to be applied correctly, the shell
script you write must have the following 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

The comment template replaces all the lines between the
@samp{Copyright} line (e.g., line 5) and the first separator line
(e.g., line 9). Everything else in the file will remain immutable.

From time to time, we use the @code{tuneup} functionality on the
`trunk/Scripts' directory structure to update the copyright and
license notice of all the shell scripts we have therein.

@subsubheading Maintaining @file{.svg} files

If scalable vector graphics are found, the @code{tuneup} functionality
reads a metadata template
(@file{trunk/Scripts/Functions/Tuneup/Config/svg_metadata.sed}) and
applies it to all files found, one by one. Immediatly after the
metadata template has been applied and, before passing to next file,
all unused definition are removed from file, too.

The metadata we apply from the metadata template is created dynamicaly
using the file found absolute path, the workstation time information
and the @command{centos-art.sh} script copyright information as
reference.  Additionally, the @emph{Creative Common
Distribution-ShareAlike 3.0 License} is also set in the metadata.

The elimination of unused definitions inside SVG files takes place
through the @option{--vacuum-defs} option of @command{inkscape}
command-line interface.

Frequently, we use the @code{tuneup} functionality on the
@file{trunk/Identity/Models} and @file{trunk/Identity/Themes/Models}
directory structure to update metadata and remove unused definitions
from design models therein.

@subsubheading Maintaining @file{.xhtml} files

If web pages are found, the @code{tuneup} functionality transforms web
page headings to make them accessible through a table of contents.
The table of contents is expanded in place, wherever the @code{<div
class="toc"></div>} piece of code be in the page. 

Once the @code{<div class="toc"></div>} piece of code has be expanded,
there is no need to put anything else in the page. You can run the
@code{tuneup} functionality everytime you update the heading
information so as to update the table of contents, too.

In order for the @code{tuneup} functionality to transform headings,
you need to put headings in just one line using one of the following
forms:

@verbatim
<h1><a name="">Title</a></h1>
<h1><a href="">Title</a></h1>
<h1><a name="" href="">Title</a></h1>
@end verbatim

In the example above, h1 can vary from h1 to h6. Closing tag must be
present and also match the openning tag. The value of @option{name}
and @option{href} options from the anchor element are set dynamically
using the md5sum output of combining the page location, the
@code{head-} string and the heading string.  If any of the components
used to build the heading reference changes, you need to run the the
@code{tuneup} functionality in order for the anchor elements to use
the correct information.

Frequently, we use the @code{tuneup} functionality on the
@file{trunk/Identity/Webenv/App/Home} directory structure to update
the heading information and the related table of contents of web pages
therein.

@subheading Usage

@subsubheading Synopsis

@command{centos-art tuneup [OPTIONS] path/to/dir}

@subsubheading Options

@table @option
@item --quiet
Supress all output messages, including confirmation question. Use this
option with care.
@item --filter='regex'
Reduce the amount of files to process using @samp{regex} as pattern.
@item --answer-yes
Assume `yes' to all confirmation questions.
@item --dont-commit-changes
Supress all @code{commit} and @code{update} actions realized over
files already processed, before and after the action itself had took
place in the working copy.
@end table

@subheading See also

@itemize
@item @ref{Directories trunk Scripts Functions}
@item @ref{Directories trunk Scripts}
@item @ref{Directories trunk}
@end itemize