Blame tcar-scripts-tuneup-docs/Manpages/tuneup.asciidoc

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

Title

Alain Reguera Delgado 4c7d62

Title

Alain Reguera Delgado 4c7d62

Title

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