Blame Documentation/Models/Docbook/Tcar-ug/Scripts/Bash/tuneup.docbook

b6bc43
<refentry id="scripts-bash-tuneup">
2a23a6
b6bc43
    <refmeta>
b6bc43
        <refentrytitle>tuneup</refentrytitle>
b6bc43
        <indexterm type="specific-function">
b6bc43
            <primary>Standardize maintainance tasks inside &TCAR;</primary>
b6bc43
        </indexterm>
b6bc43
    </refmeta>
2a23a6
b6bc43
    <refnamediv>
b6bc43
        <refname>tuneup</refname>
b6bc43
        <refpurpose>Standardize maintainance tasks inside &TCAR;</refpurpose>
b6bc43
    </refnamediv>
2a23a6
b6bc43
    <refsynopsisdiv>
2a23a6
    <para>
2a23a6
        The <varname>DIRECTORY</varname> parameter specifies the
2a23a6
        directory path, inside the working copy of &TCAR;, where the
2a23a6
        files you want to process are stored in.  This paramter can be
2a23a6
        provided more than once in order to process more than one
2a23a6
        directory path in a single command execution.  When this
2a23a6
        parameter is not provided, the current directory path where
2a23a6
        the command was called from is used instead.
2a23a6
    </para>
b6bc43
    </refsynopsisdiv>
f0ae99
b6bc43
    <refsection id="scripts-bash-tuneup-description">
f0ae99
    <title>Description</title>
2a23a6
2a23a6
    <para>
2a23a6
        Tasks related to file maintainance are repetitive. You might
2a23a6
        find yourself doing them time after time inside the working
2a23a6
        copy of &TCAR;. Some of these maintainance tasks do update top
2a23a6
        comments on shell scripts, create table of contents for web
2a23a6
        pages, update metadata related to design models and remove
2a23a6
        unused definitions from design models.
2a23a6
    </para>
2a23a6
2a23a6
    <para>
2a23a6
        When you execute the tuneup functionality of centos-art.sh
2a23a6
        script, it looks for all files that match the supported
2a23a6
        extensions (e.g., <filename class="extension">.sh</filename>,
2a23a6
        <filename class="extension">.svg</filename> and 
2a23a6
        class="extension">.xhtml</filename>) in the directory
2a23a6
        specified, builds a list with them and applies the
b6bc43
        maintainance tasks using file extensions as refentry.
2a23a6
    </para>
2a23a6
2a23a6
    <para>
2a23a6
        When shell scripts are found, the <function>tuneup</function>
2a23a6
        functionality of centos-art.sh script reads a comment template
2a23a6
        from
47422e
        <filename>Scripts/Functions/Tuneup/Shell/Config/topcomment.sed</filename>
2a23a6
        and applies it to all shell scripts found, one by one. As
2a23a6
        result, all shell scripts will end up having the same
2a23a6
        copyright and license information the comment template does.
2a23a6
    </para>
2a23a6
    <para>
2a23a6
        In order for the shell script top comment template to be
2a23a6
        applied correctly, the shell scripts you write must have the
2a23a6
        structure described in <xref linkend="scripts-bash-tuneup-fig1" />.
2a23a6
    </para>
2a23a6
2a23a6
    <example id="scripts-bash-tuneup-fig1">
2a23a6
    <title>Shell script top-comment template.</title>
2a23a6
    <screenshot>
2a23a6
    <screeninfo>Shell script top-comment template.</screeninfo>
2a23a6
    <mediaobject>
2a23a6
    <textobject>
2a23a6
<programlisting>
2a23a6
 1| #!/bin/bash
2a23a6
 2| #
2a23a6
 3| # doSomething.sh -- The function description goes here.
2a23a6
 4| # 
2a23a6
 5| # Copyright
2a23a6
 6| #
2a23a6
 7| # ...
2a23a6
 8| #
2a23a6
 9| # ----------------------------------------------------------------------
2a23a6
10| # $Id$
2a23a6
11| # ----------------------------------------------------------------------
2a23a6
12|
2a23a6
13| function doSomething {
2a23a6
14|     
2a23a6
15| }
2a23a6
</programlisting>
2a23a6
    </textobject>
2a23a6
    </mediaobject>
2a23a6
    </screenshot>
2a23a6
    </example>
2a23a6
2a23a6
    <para>
2a23a6
        The <function>tuneup</function> functionality of
2a23a6
        <command>centos-art.sh</command> script replaces all lines
2a23a6
        between the <literal>Copyright</literal> line (e.g., line 5)
2a23a6
        and the first separator line (e.g., line 9), inclusively.
2a23a6
        Everything else will remain immutable in the file.
2a23a6
    </para>
2a23a6
2a23a6
    <para>
2a23a6
        When scalable vector graphics are found, the tuneup
2a23a6
        functionality reads a SVG metadata template from
47422e
        <filename>Scripts/Functions/Tuneup/Svg/Config/metadata.sed</filename>
2a23a6
        and applies it to all files found, one by one. Immediatly
2a23a6
        after the metadata template has been applied and, before
2a23a6
        passing to next file, all unused definition are removed from
2a23a6
        the file, too.
2a23a6
    </para>
2a23a6
    <para>
2a23a6
        The metadata applied by the SVG metadata template is created
2a23a6
        dynamicaly combining the absolute path of the file being
2a23a6
        currently modified, the workstation's date information, the
2a23a6
        <command>centos-art.sh</command> script copyright holder
b6bc43
        (e.g., =COPYRIGHT_HOLDER=) as refentry and the Creative
2a23a6
        Common Distribution-ShareAlike 3.0 License as default license
2a23a6
        to release SVG files.
2a23a6
    </para>
2a23a6
    <para>
2a23a6
        The elimination of unused definitions inside SVG files takes
2a23a6
        place through Inkscape's <option>--vacuum-defs</option>
2a23a6
        option, as described in its man page (e.g., <command>man
2a23a6
        inkscape</command>).
2a23a6
    </para>
2a23a6
2a23a6
    <para>
2a23a6
        When HTML files are found, the <function>tuneup</function>
2a23a6
        functionality of <command>centos-art.sh</command> script
2a23a6
        transforms web page headings to make them accessible through a
2a23a6
        table of contents.  The table of contents is expanded in
2a23a6
        place, wherever the <div
2a23a6
        class="toc"></div> piece of code be in the
2a23a6
        file.  Once the table of contents has been expanded, there is
2a23a6
        no need to put anything else in the page.  You can run the
2a23a6
        <function>tuneup</function> functionality everytime you update
2a23a6
        the heading information so as to update the table of contents,
2a23a6
        too.
2a23a6
    </para>
2a23a6
    <para>
2a23a6
        In order for this functionality to build the table of contents
2a23a6
        from headings, you need to put headings in just one line. The
2a23a6
        headin level can vary from h1 to h6
2a23a6
        with attribute definitions accepted.  Closing tag must be
2a23a6
        present and also match the openning tag.  Inside the heading
2a23a6
        definition an anchor definition must be present with attribute
2a23a6
        definitions accepted. The value of <property>name</property>
2a23a6
        and <property>href</property> attributes from the anchor
2a23a6
        element are set dynamically using the md5sum output of
2a23a6
        combining the page location, the <literal>head-</literal>
2a23a6
        string and the heading content itself.  If any of the
b6bc43
        components used to build the heading refentry changes, you
2a23a6
        need to run the the tuneup functionality of
2a23a6
        <command>centos-art.sh</command> script in order for the
2a23a6
        anchor elements to use the correct information.
2a23a6
    </para>
2a23a6
    <para>
2a23a6
        For example, the headings shown in 
2a23a6
        linkend="scripts-bash-tuneup-fig2" /> produces the table of
2a23a6
        contents shown in <xref linkend="scripts-bash-tuneup-fig3" />.
2a23a6
    </para>
2a23a6
2a23a6
    <example id="scripts-bash-tuneup-fig2">
2a23a6
    <title>HTML heading definition.</title>
2a23a6
    <screenshot>
2a23a6
    <screeninfo>HTML heading definition.</screeninfo>
2a23a6
    <mediaobject>
2a23a6
    <textobject>
2a23a6
<programlisting>
2a23a6
<h1 class="title"><a name="head-8a23b56a28dfa7277d176576f217054a">Forms</a></h1>
2a23a6
<h2 class="title"><a name="head-629f38bc607f2a270177106b450aeae3">Elements</a></h2>
2a23a6
<h2 class="title"><a name="head-f49cae1d73592c984bbb0bffb1d5699a">Recommendations</a></h2>
2a23a6
</programlisting>
2a23a6
    </textobject>
2a23a6
    </mediaobject>
2a23a6
    </screenshot>
2a23a6
    </example>
2a23a6
2a23a6
    <example id="scripts-bash-tuneup-fig3">
2a23a6
    <title>HTML table of contents definition.</title>
2a23a6
    <screenshot>
2a23a6
    <screeninfo>HTML table of contents definition.</screeninfo>
2a23a6
    <mediaobject>
2a23a6
    <textobject>
2a23a6
<programlisting>
2a23a6
<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>
2a23a6
</programlisting>
2a23a6
    </textobject>
2a23a6
    </mediaobject>
2a23a6
    </screenshot>
2a23a6
    </example>
b6bc43
    </refsection>
b6bc43
b6bc43
    <refsection id="scripts-bash-tuneup-options">
b6bc43
    <title>Options</title>
b6bc43
    <para>
b6bc43
        The <function>tuneup</function> functionality accepts the
b6bc43
        following options: 
b6bc43
    </para>
b6bc43
b6bc43
    <variablelist>
b6bc43
    <varlistentry>
b6bc43
    <term><option>--quiet</option></term>
b6bc43
    <listitem>
b6bc43
    <para>
b6bc43
        Supress all output messages except error messages.  When this
b6bc43
        option is passed, all confirmation requests are supressed and
b6bc43
        a possitive answer is assumed for them, just as if the
b6bc43
        <option>--answer-yes</option> option would have been provided.
b6bc43
    </para>
b6bc43
    </listitem>
b6bc43
    </varlistentry>
b6bc43
b6bc43
    <varlistentry>
b6bc43
    <term><option>--answer-yes</option></term>
b6bc43
    <listitem>
b6bc43
    <para>
b6bc43
       Assume <emphasis>yes</emphasis> to all confirmation requests.
b6bc43
    </para>
b6bc43
    </listitem>
b6bc43
    </varlistentry>
b6bc43
b6bc43
    <varlistentry>
b6bc43
    <term><option>--filter="REGEX"</option></term>
b6bc43
    <listitem>
b6bc43
    <para>
b6bc43
        Reduce the list of files to process inside
b6bc43
        <replaceable>path/to/dir</replaceable> using
b6bc43
        <replaceable>REGEX</replaceable> as pattern.  You can use this
b6bc43
        option to control the amount of files you want to tuneup.  The
b6bc43
        deeper you go into the directory structure the more specific
b6bc43
        you'll be about the files you want to tuneup.  When you cannot
b6bc43
        go deeper into the directory structure through
b6bc43
        <replaceable>path/to/dir</replaceable> specification, use this
b6bc43
        option to reduce the list of files therein.
b6bc43
    </para>
b6bc43
    </listitem>
b6bc43
    </varlistentry>
b6bc43
b6bc43
    <varlistentry>
3b9515
    <term><option>--synchronize</option></term>
b6bc43
    <listitem>
b6bc43
    <para>
b6bc43
        Synchronizes available changes between the working copy and
b6bc43
        the central repository.
b6bc43
    </para>
b6bc43
    </listitem>
b6bc43
    </varlistentry>
b6bc43
    </variablelist>
b6bc43
    </refsection>
f0ae99
b6bc43
    <refsection id="scripts-bash-tuneup-environment">
a491ef
    <title>Function Specific Environment</title>
f0ae99
    <para>
f0ae99
        ...
f0ae99
    </para>
b6bc43
    </refsection>
f0ae99
b6bc43
    <refsection id="scripts-bash-tuneup-authors">
f0ae99
    <title>Authors</title>
f0ae99
    <para>
f0ae99
        The following people have worked in the
f0ae99
        <function>tuneup</function> functionality:
f0ae99
    </para>
f0ae99
    <itemizedlist>
f0ae99
    <listitem>
f0ae99
    <para>
a491ef
        Alain Reguera Delgado <<ulink url="mailto:alain.reguera@gmail.com">alain.reguera@gmail.com</ulink>>, =COPYRIGHT_YEAR_LIST=
f0ae99
    </para>
f0ae99
    </listitem>
f0ae99
    </itemizedlist>
b6bc43
    </refsection>
f0ae99
b6bc43
    <refsection id="scripts-bash-tuneup-licence">
f0ae99
    <title>License</title>
a491ef
f0ae99
    <para>
a491ef
        Copyright © =COPYRIGHT_YEAR_LIST= The CentOS Project
a491ef
    </para>
f0ae99
 
a491ef
    <para>
a491ef
        This program is free software; you can redistribute it and/or
a491ef
        modify it under the terms of the GNU General Public License as
a491ef
        published by the Free Software Foundation; either version 2 of
a491ef
        the License, or (at your option) any later version.
a491ef
    </para>
f0ae99
 
a491ef
    <para>
a491ef
        This program is distributed in the hope that it will be
a491ef
        useful, but WITHOUT ANY WARRANTY; without even the implied
a491ef
        warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
a491ef
        PURPOSE.  See the GNU General Public License for more details.
a491ef
    </para>
f0ae99
 
a491ef
    <para>
a491ef
        You should have received a copy of the GNU General Public
a491ef
        License along with this program; if not, write to the Free
a491ef
        Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139,
a491ef
        USA.
f0ae99
    </para>
b6bc43
    </refsection>
2a23a6
b6bc43
</refentry>