Blame Automation/Modules/Tuneup/Manuals/tuneup.asciidoc

Alain Reguera Delgado ac5473
tuneup(1)
Alain Reguera Delgado ac5473
=========
Alain Reguera Delgado ac5473
Alain Reguera Delgado ac5473
Name
Alain Reguera Delgado ac5473
----
Alain Reguera Delgado ac5473
Alain Reguera Delgado aa198e
tuneup - Standardizes source code maintenance tasks inside the
Alain Reguera Delgado aa198e
repository.
Alain Reguera Delgado ac5473
Alain Reguera Delgado ac5473
Synopsis
Alain Reguera Delgado ac5473
--------
Alain Reguera Delgado ac5473
Alain Reguera Delgado aa198e
*centos-art.sh tuneup [FILE ...|DIRECTORY ...] [--filter="REGEX"]*::
Alain Reguera Delgado aa198e
    Execute source code maintenance tasks.
Alain Reguera Delgado ac5473
Alain Reguera Delgado ac5473
Description
Alain Reguera Delgado ac5473
-----------
Alain Reguera Delgado ac5473
Alain Reguera Delgado aa198e
When you run the *tuneup* module it may enter into either file or
Alain Reguera Delgado aa198e
directory processing, based on whether you provide a file or directory
Alain Reguera Delgado aa198e
as argument for processing in the command-line.  When you provide a
Alain Reguera Delgado aa198e
file as argument to *tuneup* module, it uses the file's extension as
Alain Reguera Delgado aa198e
reference for applying maintenance tasks on that file as described in
Alain Reguera Delgado aa198e
<<supported-file-extensions>>.  When you provide a directory as
Alain Reguera Delgado aa198e
argument, *tuneup* looks for all files with supported extensions
Alain Reguera Delgado aa198e
inside that directory and then process them, one by one.
Alain Reguera Delgado aa198e
Alain Reguera Delgado aa198e
The *tuneup* module exists to automate frequent tasks related to code
Alain Reguera Delgado aa198e
maintenance, inside the repository (see <<examples>>). It is advisable
Alain Reguera Delgado aa198e
to run *tuneup* module over your files from time to time so they all
Alain Reguera Delgado aa198e
have a common look and feel.
Alain Reguera Delgado aa198e
Alain Reguera Delgado aa198e
[[supported-file-extensions]]
Alain Reguera Delgado aa198e
Supported File Extensions
Alain Reguera Delgado aa198e
-------------------------
Alain Reguera Delgado aa198e
Alain Reguera Delgado aa198e
The *tuneup* module supports maintenance tasks for the following file
Alain Reguera Delgado aa198e
extensions:
Alain Reguera Delgado aa198e
Alain Reguera Delgado aa198e
.svgz, .svg
Alain Reguera Delgado aa198e
~~~~~~~~~~~
Alain Reguera Delgado aa198e
Alain Reguera Delgado aa198e
Provides maintenance tasks for Scalable Vector Graphics (SVG).
Alain Reguera Delgado aa198e
Alain Reguera Delgado aa198e
When processing svg files, *tuneup* uses the inkscape's --vaccumm
Alain Reguera Delgado aa198e
option to cleanup source code and applies few sed commands to modify
Alain Reguera Delgado aa198e
inkscape's metadata using dynamic information like document title,
Alain Reguera Delgado aa198e
date, copyright information, urls, and locale information retrieved
Alain Reguera Delgado aa198e
from from centos-art.sh script and the file location inside the
Alain Reguera Delgado aa198e
repository.
Alain Reguera Delgado aa198e
Alain Reguera Delgado aa198e
Each time you create a new svg file or change one, it is advisable to
Alain Reguera Delgado aa198e
run *tuneup* module over it.
Alain Reguera Delgado aa198e
Alain Reguera Delgado aa198e
.xhtml, .html, .htm
Alain Reguera Delgado aa198e
~~~~~~~~~~~~~~~~~~~
Alain Reguera Delgado aa198e
Alain Reguera Delgado aa198e
Provides maintenance tasks for HyperText Markup Language (HTML).
Alain Reguera Delgado aa198e
Alain Reguera Delgado aa198e
When processing html-like files, *tuneup* changes each file to create
Alain Reguera Delgado aa198e
a table of contents for each heading constructions (see below) first
Alain Reguera Delgado aa198e
and then transforms the (probably malformed) HTML markup into valid
Alain Reguera Delgado aa198e
XHTML documents using xmllint(1) program.
Alain Reguera Delgado aa198e
Alain Reguera Delgado aa198e
In order for *tuneup* to create the table of contents correctly, the
Alain Reguera Delgado aa198e
heading construction inside the HTML document must comply the
Alain Reguera Delgado aa198e
following restrictions:
Alain Reguera Delgado aa198e
Alain Reguera Delgado aa198e
1. Headings must have one of the following forms:
Alain Reguera Delgado aa198e
+
Alain Reguera Delgado aa198e
----------------------------------------------------------------------
Alain Reguera Delgado aa198e

Title

Alain Reguera Delgado aa198e

Title

Alain Reguera Delgado aa198e

Title

Alain Reguera Delgado aa198e
----------------------------------------------------------------------
Alain Reguera Delgado aa198e
+
Alain Reguera Delgado aa198e
In these constructions, the heading level may vary from h1 to h6 but
Alain Reguera Delgado aa198e
the heading content (e.g., ``Title'') must not be empty.
Alain Reguera Delgado aa198e
Alain Reguera Delgado aa198e
When producing table of contents through *tuneup* module, both `name'
Alain Reguera Delgado aa198e
and `href' attributes in the anchor element of each heading will be
Alain Reguera Delgado aa198e
reset dynamically using a md5 string.  The md5 string used in these
Alain Reguera Delgado aa198e
cases is based on the heading content (i.e., the text shown as heading
Alain Reguera Delgado aa198e
when the page is rendered in a browser) and won't change until you
Alain Reguera Delgado aa198e
change the heading content and run *tuneup* module over it again.
Alain Reguera Delgado aa198e
Alain Reguera Delgado aa198e
The final table of contents will be expanded wherever you set the
Alain Reguera Delgado aa198e
+
+ HTML construction as a line of its own
Alain Reguera Delgado aa198e
inside the file being processed.
Alain Reguera Delgado aa198e
Alain Reguera Delgado aa198e
.sh
Alain Reguera Delgado aa198e
~~~
Alain Reguera Delgado aa198e
Alain Reguera Delgado aa198e
Provides maintenance tasks for Bash scripts. 
Alain Reguera Delgado aa198e
Alain Reguera Delgado aa198e
When processing sh files, *tuneup* changes the file to update the
Alain Reguera Delgado aa198e
written by section, copyright year and license information inside
Alain Reguera Delgado aa198e
shell scripts' top comment. Later, it corrects variable name's
Alain Reguera Delgado aa198e
references to be all written in upper-case between brackets (e.g.,
Alain Reguera Delgado aa198e
``${VARNAME}'').
Alain Reguera Delgado aa198e
Alain Reguera Delgado aa198e
In order for *tuneup* module to update the top comment of your shell
Alain Reguera Delgado aa198e
scripts correctly, it is necessary that your top comments have one
Alain Reguera Delgado aa198e
+written by+ line followed by a line of 70 number-sign (\#)
Alain Reguera Delgado aa198e
characters, as illustrated in <<top-comment>> This is the basic
Alain Reguera Delgado aa198e
construction.  Everything between the +written by+ line and the last
Alain Reguera Delgado aa198e
line of 70 number-sign characters will be replaced by *tuneup* module
Alain Reguera Delgado aa198e
top-comment template which includes people names, copyright and
Alain Reguera Delgado aa198e
license information. Everything else does remain untouched.
Alain Reguera Delgado aa198e
Alain Reguera Delgado aa198e
[[top-comment]]
Alain Reguera Delgado aa198e
.Top-comment convention used by tuneup module.
Alain Reguera Delgado aa198e
======================================================================
Alain Reguera Delgado aa198e
----------------------------------------------------------------------
Alain Reguera Delgado aa198e
#!/bin/bash
Alain Reguera Delgado aa198e
######################################################################
Alain Reguera Delgado aa198e
#
Alain Reguera Delgado aa198e
#   ${FILE}.sh -- ${DESCRIPTION}
Alain Reguera Delgado aa198e
#
Alain Reguera Delgado aa198e
#   Written by:
Alain Reguera Delgado aa198e
#
Alain Reguera Delgado aa198e
######################################################################
Alain Reguera Delgado aa198e
----------------------------------------------------------------------
Alain Reguera Delgado aa198e
======================================================================
Alain Reguera Delgado aa198e
Alain Reguera Delgado aa198e
[[options]]
Alain Reguera Delgado aa198e
Options
Alain Reguera Delgado aa198e
-------
Alain Reguera Delgado aa198e
Alain Reguera Delgado df8ff9
*--help*::
Alain Reguera Delgado df8ff9
    Print module's documentation.
Alain Reguera Delgado df8ff9
*--version*::
Alain Reguera Delgado df8ff9
    Print module's version.
Alain Reguera Delgado aa198e
*--filter="REGEX"*::
Alain Reguera Delgado aa198e
    This option let you reduce the number of files you want to process
Alain Reguera Delgado aa198e
    by applying a (POSIX-egrep) regular expression to the list of file
Alain Reguera Delgado aa198e
    paths returned for processing. This option is specially useful
Alain Reguera Delgado aa198e
    when you need to process files inside a directory structure based
Alain Reguera Delgado aa198e
    on a specific name patterns.
Alain Reguera Delgado aa198e
Alain Reguera Delgado aa198e
[[examples]]
Alain Reguera Delgado aa198e
Alain Reguera Delgado aa198e
Examples
Alain Reguera Delgado aa198e
--------
Alain Reguera Delgado aa198e
Alain Reguera Delgado aa198e
*centos-art.sh tuneup Automation/Scripts*::
Alain Reguera Delgado aa198e
    This command updates the top comment and variable name references
Alain Reguera Delgado aa198e
    of all files inside the Automation/Scripts directory, recursively.
Alain Reguera Delgado aa198e
Alain Reguera Delgado aa198e
*centos-art.sh tuneup Automation/Scripts/tcar_printVersion.sh*::
Alain Reguera Delgado aa198e
    This commands updates the top comment and variable name references
Alain Reguera Delgado aa198e
    inside the tcar_printVersion.sh file only.
Alain Reguera Delgado aa198e
Alain Reguera Delgado aa198e
*centos-art.sh tuneup Automation/Scripts --filter="tcar_print.+\.sh$"*::
Alain Reguera Delgado aa198e
    This command updates the top comment and variable name refrences
Alain Reguera Delgado aa198e
    inside files which name only begins with ``tcar_print'' followed
Alain Reguera Delgado aa198e
    by any character and ends with ``.sh''. All other files won't be
Alain Reguera Delgado aa198e
    touched.
Alain Reguera Delgado aa198e
Alain Reguera Delgado aa198e
[[author]]
Alain Reguera Delgado ac5473
Alain Reguera Delgado ac5473
Author
Alain Reguera Delgado ac5473
------
Alain Reguera Delgado ac5473
Alain Reguera Delgado aa198e
The *tuneup* module has received contributions from the following
Alain Reguera Delgado aa198e
people:
Alain Reguera Delgado aa198e
Alain Reguera Delgado aa198e
    * mailto:al@centos.org.cu[Alain Reguera Delgado], =COPYRIGHT_YEAR_FIRST=-=COPYRIGHT_YEAR_LAST=
Alain Reguera Delgado aa198e
Alain Reguera Delgado aa198e
[[copyright]]
Alain Reguera Delgado ac5473
Alain Reguera Delgado ac5473
Copyright
Alain Reguera Delgado ac5473
---------
Alain Reguera Delgado ac5473
Alain Reguera Delgado aa198e
Copyright (C) =COPYRIGHT_YEAR_FIRST=-=COPYRIGHT_YEAR_LAST= =COPYRIGHT_HOLDER=
Alain Reguera Delgado ac5473
Alain Reguera Delgado aa198e
The *tuneup* module is free software; you can redistribute it and/or
Alain Reguera Delgado aa198e
modify it under the terms of the GNU General Public License as
Alain Reguera Delgado aa198e
published by the Free Software Foundation; either version 2 of the
Alain Reguera Delgado aa198e
License, or (at your option) any later version.
Alain Reguera Delgado ac5473
Alain Reguera Delgado aa198e
Tue *tuneup* module is distributed in the hope that it will be useful,
Alain Reguera Delgado aa198e
but WITHOUT ANY WARRANTY; without even the implied warranty of
Alain Reguera Delgado ac5473
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Alain Reguera Delgado ac5473
General Public License for more details.
Alain Reguera Delgado ac5473
Alain Reguera Delgado ac5473
You should have received a copy of the GNU General Public License
Alain Reguera Delgado ac5473
along with this program; if not, write to the Free Software
Alain Reguera Delgado ac5473
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
Alain Reguera Delgado ac5473
Alain Reguera Delgado aa198e
[[see-also]]
Alain Reguera Delgado aa198e
Alain Reguera Delgado ac5473
See Also
Alain Reguera Delgado ac5473
--------
Alain Reguera Delgado ac5473
Alain Reguera Delgado aa198e
centos-art.sh(1), xmllint(1)
Alain Reguera Delgado ac5473
Alain Reguera Delgado ac5473
// vim: set syntax=asciidoc: