<refentry id="scripts-bash-tuneup">

    <refmeta>

        <refentrytitle>tuneup</refentrytitle>

        <indexterm type="specific-function">

            <primary>Standardize maintainance tasks inside &TCAR;</primary>

        </indexterm>

    </refmeta>

    <refnamediv>

        <refname>tuneup</refname>

        <refpurpose>Standardize maintainance tasks inside &TCAR;</refpurpose>

    </refnamediv>

    <refsynopsisdiv>

    <para>

        The <varname>DIRECTORY</varname> parameter specifies the

        directory path, inside the working copy of &TCAR;, where the

        files you want to process are stored in.  This paramter can be

        provided more than once in order to process more than one

        directory path in a single command execution.  When this

        parameter is not provided, the current directory path where

        the command was called from is used instead.

    </para>

    </refsynopsisdiv>

    <refsection id="scripts-bash-tuneup-description">

    <title>Description</title>

    <para>

        Tasks related to file maintainance are repetitive. You might

        find yourself doing them time after time inside the working

        copy of &TCAR;. Some of these maintainance tasks do update top

        comments on shell scripts, create table of contents for web

        pages, update metadata related to design models and remove

        unused definitions from design models.

    </para>

    <para>

        When you execute the tuneup functionality of centos-art.sh

        script, it looks for all files that match the supported

        extensions (e.g., <filename class="extension">.sh</filename>,

        <filename class="extension">.svg</filename> and 

        class="extension">.xhtml</filename>) in the directory

        specified, builds a list with them and applies the

        maintainance tasks using file extensions as refentry.

    </para>

    <para>

        When shell scripts are found, the <function>tuneup</function>

        functionality of centos-art.sh script reads a comment template

        from

        <filename>Scripts/Functions/Tuneup/Shell/Config/topcomment.sed</filename>

        and applies it to all shell scripts found, one by one. As

        result, all shell scripts will end up having the same

        copyright and license information the comment template does.

    </para>

    <para>

        In order for the shell script top comment template to be

        applied correctly, the shell scripts you write must have the

        structure described in <xref linkend="scripts-bash-tuneup-fig1" />.

    </para>

    <example id="scripts-bash-tuneup-fig1">

    <title>Shell script top-comment template.</title>

    <screenshot>

    <screeninfo>Shell script top-comment template.</screeninfo>

    <mediaobject>

    <textobject>

<programlisting>

 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| }

</programlisting>

    </textobject>

    </mediaobject>

    </screenshot>

    </example>

    <para>

        The <function>tuneup</function> functionality of

        <command>centos-art.sh</command> script replaces all lines

        between the <literal>Copyright</literal> line (e.g., line 5)

        and the first separator line (e.g., line 9), inclusively.

        Everything else will remain immutable in the file.

    </para>

    <para>

        When scalable vector graphics are found, the tuneup

        functionality reads a SVG metadata template from

        <filename>Scripts/Functions/Tuneup/Svg/Config/metadata.sed</filename>

        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

        the file, too.

    </para>

    <para>

        The metadata applied by the SVG metadata template is created

        dynamicaly combining the absolute path of the file being

        currently modified, the workstation's date information, the

        <command>centos-art.sh</command> script copyright holder

        (e.g., =COPYRIGHT_HOLDER=) as refentry and the Creative

        Common Distribution-ShareAlike 3.0 License as default license

        to release SVG files.

    </para>

    <para>

        The elimination of unused definitions inside SVG files takes

        place through Inkscape's <option>--vacuum-defs</option>

        option, as described in its man page (e.g., <command>man

        inkscape</command>).

    </para>

    <para>

        When HTML files are found, the <function>tuneup</function>

        functionality of <command>centos-art.sh</command> script

        transforms web page headings to make them accessible through a

        table of contents.  The table of contents is expanded in

        place, wherever the <div

        class="toc"></div> piece of code be in the

        file.  Once the table of contents has been expanded, there is

        no need to put anything else in the page.  You can run the

        <function>tuneup</function> functionality everytime you update

        the heading information so as to update the table of contents,

        too.

    </para>

    <para>

        In order for this functionality to build the table of contents

        from headings, you need to put headings in just one line. The

        headin level can vary from h1 to h6

        with attribute definitions accepted.  Closing tag must be

        present and also match the openning tag.  Inside the heading

        definition an anchor definition must be present with attribute

        definitions accepted. The value of <property>name</property>

        and <property>href</property> attributes from the anchor

        element are set dynamically using the md5sum output of

        combining the page location, the <literal>head-</literal>

        string and the heading content itself.  If any of the

        components used to build the heading refentry changes, you

        need to run the the tuneup functionality of

        <command>centos-art.sh</command> script in order for the

        anchor elements to use the correct information.

    </para>

    <para>

        For example, the headings shown in 

        linkend="scripts-bash-tuneup-fig2" /> produces the table of

        contents shown in <xref linkend="scripts-bash-tuneup-fig3" />.

    </para>

    <example id="scripts-bash-tuneup-fig2">

    <title>HTML heading definition.</title>

    <screenshot>

    <screeninfo>HTML heading definition.</screeninfo>

    <mediaobject>

    <textobject>

<programlisting>

<h1 class="title"><a name="head-8a23b56a28dfa7277d176576f217054a">Forms</a></h1>

<h2 class="title"><a name="head-629f38bc607f2a270177106b450aeae3">Elements</a></h2>

<h2 class="title"><a name="head-f49cae1d73592c984bbb0bffb1d5699a">Recommendations</a></h2>

</programlisting>

    </textobject>

    </mediaobject>

    </screenshot>

    </example>

    <example id="scripts-bash-tuneup-fig3">

    <title>HTML table of contents definition.</title>

    <screenshot>

    <screeninfo>HTML table of contents definition.</screeninfo>

    <mediaobject>

    <textobject>

<programlisting>

<div class="toc"> <p>Table of contents</p> <dl><dt><a href="#head-8a23b56a28dfa7277d176576f217054a">Forms</a> <dl><dt><a href="#head-629f38bc607f2a270177106b450aeae3">Elements</a> </dt><dt><a href="#head-f49cae1d73592c984bbb0bffb1d5699a">Recommendations</a> </dt></dl> </dt></dl> </div>

</programlisting>

    </textobject>

    </mediaobject>

    </screenshot>

    </example>

    </refsection>

    <refsection id="scripts-bash-tuneup-options">

    <title>Options</title>

    <para>

        The <function>tuneup</function> functionality accepts the

        following options: 

    </para>

    <variablelist>

    <varlistentry>

    <term><option>--quiet</option></term>

    <listitem>

    <para>

        Supress all output messages except error messages.  When this

        option is passed, all confirmation requests are supressed and

        a possitive answer is assumed for them, just as if the

        <option>--answer-yes</option> option would have been provided.

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term><option>--answer-yes</option></term>

    <listitem>

    <para>

       Assume <emphasis>yes</emphasis> to all confirmation requests.

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term><option>--filter="REGEX"</option></term>

    <listitem>

    <para>

        Reduce the list of files to process inside

        <replaceable>path/to/dir</replaceable> using

        <replaceable>REGEX</replaceable> as pattern.  You can use this

        option to control the amount of files you want to tuneup.  The

        deeper you go into the directory structure the more specific

        you'll be about the files you want to tuneup.  When you cannot

        go deeper into the directory structure through

        <replaceable>path/to/dir</replaceable> specification, use this

        option to reduce the list of files therein.

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term><option>--synchronize</option></term>

    <listitem>

    <para>

        Synchronizes available changes between the working copy and

        the central repository.

    </para>

    </listitem>

    </varlistentry>

    </variablelist>

    </refsection>

    <refsection id="scripts-bash-tuneup-environment">

    <title>Function Specific Environment</title>

    <para>

        ...

    </para>

    </refsection>

    <refsection id="scripts-bash-tuneup-authors">

    <title>Authors</title>

    <para>

        The following people have worked in the

        <function>tuneup</function> functionality:

    </para>

    <itemizedlist>

    <listitem>

    <para>

        Alain Reguera Delgado <<ulink url="mailto:alain.reguera@gmail.com">alain.reguera@gmail.com</ulink>>, =COPYRIGHT_YEAR_LIST=

    </para>

    </listitem>

    </itemizedlist>

    </refsection>

    <refsection id="scripts-bash-tuneup-licence">

    <title>License</title>

    <para>

        Copyright © =COPYRIGHT_YEAR_LIST= =COPYRIGHT_HOLDER=

    </para>

    <para>

        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.

    </para>

    <para>

        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.

    </para>

    <para>

        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.

    </para>

    </refsection>

</refentry>