tcar-tuneup(1)
==============

Name
----

tcar-tuneup - Standardizes source code maintenance tasks inside the
repository.

Synopsis
--------

*tcar tuneup [FILE ...|DIRECTORY ...] [--filter="REGEX"]*::
    Execute source code maintenance tasks.

Description
-----------

When you run the *tuneup* command it may enter into either file or
directory processing, based on whether you provide a file or directory
as argument for processing in the command-line.  When you provide a
file as argument to *tuneup* module, it uses the file's extension as
reference for applying maintenance tasks on that file as described in
<<supported-file-extensions>>.  When you provide a directory as
argument, *tuneup* looks for all files with supported extensions
inside that directory and then process them, one by one.

The *tuneup* module exists to automate frequent tasks related to code
maintenance, inside the repository (see <<examples>>). It is advisable
to run *tuneup* module over your files from time to time so they all
have a common look and feel.

[[supported-file-extensions]]
Supported File Extensions
-------------------------

The *tuneup* module supports maintenance tasks for the following file
extensions:

.svgz, .svg
~~~~~~~~~~~

Provides maintenance tasks for Scalable Vector Graphics (SVG).

When processing svg files, *tuneup* uses the inkscape's --vaccumm
option to cleanup source code and applies few sed commands to modify
inkscape's metadata using dynamic information like document title,
date, copyright information, urls, and locale information retrieved
from from tcar.sh script and the file location inside the
repository.

Each time you create a new svg file or change one, it is advisable to
run *tuneup* module over it.

.xhtml, .html, .htm
~~~~~~~~~~~~~~~~~~~

Provides maintenance tasks for HyperText Markup Language (HTML).

When processing html-like files, *tuneup* changes each file to create
a table of contents for each heading constructions (see below) first
and then transforms the (probably malformed) HTML markup into valid
XHTML documents using xmllint(1) program.

In order for *tuneup* to create the table of contents correctly, the
heading construction inside the HTML document must comply the
following restrictions:

1. Headings must have one of the following forms:
+
----------------------------------------------------------------------
<h1><a name="">Title</a></h1>
<h1><a href="">Title</a></h1>
<h1><a name="" href="">Title</a></h1>
----------------------------------------------------------------------
+
In these constructions, the heading level may vary from h1 to h6 but
the heading content (e.g., ``Title'') must not be empty.

When producing table of contents through *tuneup* module, both `name'
and `href' attributes in the anchor element of each heading will be
reset dynamically using a md5 string.  The md5 string used in these
cases is based on the heading content (i.e., the text shown as heading
when the page is rendered in a browser) and won't change until you
change the heading content and run *tuneup* module over it again.

The final table of contents will be expanded wherever you set the
+<div class="toc"></div>+ HTML construction as a line of its own
inside the file being processed.

.sh
~~~

Provides maintenance tasks for Bash scripts. 

When processing sh files, *tuneup* changes the file to update the
written by section, copyright year and license information inside
shell scripts' top comment. Later, it corrects variable name's
references to be all written in upper-case between brackets (e.g.,
``${VARNAME}'').

In order for *tuneup* module to update the top comment of your shell
scripts correctly, it is necessary that your top comments have one
+written by+ line followed by a line of 70 number-sign (\#)
characters, as illustrated in <<top-comment>> This is the basic
construction.  Everything between the +written by+ line and the last
line of 70 number-sign characters will be replaced by *tuneup* module
top-comment template which includes people names, copyright and
license information. Everything else does remain untouched.

[[top-comment]]
.Top-comment convention used by tuneup module.
======================================================================
----------------------------------------------------------------------
#!/bin/bash
######################################################################
#
#   ${FILE}.sh -- ${DESCRIPTION}
#
#   Written by:
#
######################################################################
----------------------------------------------------------------------
======================================================================

[[options]]
Options
-------

*--help*::
    Print module's documentation.
*--version*::
    Print module's version.
*--filter="REGEX"*::
    This option let you reduce the number of files you want to process
    by applying a (POSIX-egrep) regular expression to the list of file
    paths returned for processing. This option is specially useful
    when you need to process files inside a directory structure based
    on a specific name patterns.

[[examples]]

Examples
--------

*tcar.sh tuneup Automation/Scripts*::
    This command updates the top comment and variable name references
    of all files inside the Automation/Scripts directory, recursively.

*tcar.sh tuneup Automation/Scripts/tcar_printVersion.sh*::
    This commands updates the top comment and variable name references
    inside the tcar_printVersion.sh file only.

*tcar.sh tuneup Automation/Scripts --filter="tcar_print.+\.sh$"*::
    This command updates the top comment and variable name refrences
    inside files which name only begins with ``tcar_print'' followed
    by any character and ends with ``.sh''. All other files won't be
    touched.

[[author]]

Author
------

Written by Alain Reguera Delgado

[[copyright]]

Copyright
---------

Copyright (C) =COPYRIGHT_YEAR_LAST= =COPYRIGHT_HOLDER=

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.

[[see-also]]

See Also
--------

tcar.sh(1), xmllint(1)

// vim: set syntax=asciidoc: