From 8a33f3185ebb2343735b8ac8e9dbc2cb2e160c41 Mon Sep 17 00:00:00 2001 From: Alain Reguera Delgado Date: Dec 27 2013 21:33:09 +0000 Subject: Merge branch 'tcar-scripts-tuneup-docs' into tcar-scripts-tuneup - Previously, tuneup scripts and tuneup documentation were in separate branches. This made difficult to revise the automation scripts while writing documentation. In order to make the process of writing documentation easier, this merge unifies both tuneup scripts and tuneup documentation into tcar-scripts-tuneup branch. --- diff --git a/tcar-scripts-tuneup-docs/Manpages/Locales/en_US/tuneup.asciidoc.po b/tcar-scripts-tuneup-docs/Manpages/Locales/en_US/tuneup.asciidoc.po new file mode 100644 index 0000000..b164488 --- /dev/null +++ b/tcar-scripts-tuneup-docs/Manpages/Locales/en_US/tuneup.asciidoc.po @@ -0,0 +1,392 @@ +msgid "" +msgstr "" +"Project-Id-Version: tuneup.asciidoc 0.6\n" +"POT-Creation-Date: 2013-11-07 15:18-0500\n" +"PO-Revision-Date: 2013-11-07 15:18-0500\n" +"Last-Translator: Localization SIG \n" +"Language-Team: English\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=2; plural=(n != 1);\n" + +msgid "tuneup" +msgstr "tuneup" + +msgid "1" +msgstr "1" + +msgid "" +"Standardizes source code maintenance tasks inside the repository." +msgstr "" +"Standardizes source code maintenance tasks inside the repository." + +msgid "centos-art.sh tuneup [FILE …|DIRECTORY …] [--filter=\"REGEX\"]" +msgstr "" +"centos-art.sh tuneup [FILE …|DIRECTORY …] [--filter=\"REGEX\"]" + +msgid "Execute source code maintenance tasks." +msgstr "Execute source code maintenance tasks." + +msgid "Description" +msgstr "Description" + +msgid "" +"When you run the tuneup module " +"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 . 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." +msgstr "" +"When you run the tuneup module " +"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 . 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." + +msgid "" +"The tuneup module exists to " +"automate frequent tasks related to code maintenance, inside the " +"repository (see ). It is advisable to " +"run tuneup module over your " +"files from time to time so they all have a common look and feel." +msgstr "" +"The tuneup module exists to " +"automate frequent tasks related to code maintenance, inside the " +"repository (see ). It is advisable to " +"run tuneup module over your " +"files from time to time so they all have a common look and feel." + +msgid "Supported File Extensions" +msgstr "Supported File Extensions" + +msgid "" +"The tuneup module supports " +"maintenance tasks for the following file extensions:" +msgstr "" +"The tuneup module supports " +"maintenance tasks for the following file extensions:" + +msgid ".svgz, .svg" +msgstr ".svgz, .svg" + +msgid "Provides maintenance tasks for Scalable Vector Graphics (SVG)." +msgstr "" +"Provides maintenance tasks for Scalable Vector Graphics (SVG)." + +msgid "" +"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 " +"centos-art.sh script and the file location inside the repository." +msgstr "" +"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 " +"centos-art.sh script and the file location inside the repository." + +msgid "" +"Each time you create a new svg file or change one, it is advisable " +"to run tuneup module over it." +msgstr "" +"Each time you create a new svg file or change one, it is advisable " +"to run tuneup module over it." + +msgid ".xhtml, .html, .htm" +msgstr ".xhtml, .html, .htm" + +msgid "" +"Provides maintenance tasks for HyperText Markup Language (HTML)." +msgstr "" +"Provides maintenance tasks for HyperText Markup Language (HTML)." + +msgid "" +"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." +msgstr "" +"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." + +msgid "" +"In order for tuneup to create " +"the table of contents correctly, the heading construction inside " +"the HTML document must comply the following restrictions:" +msgstr "" +"In order for tuneup to create " +"the table of contents correctly, the heading construction inside " +"the HTML document must comply the following restrictions:" + +msgid "Headings must have one of the following forms:" +msgstr "Headings must have one of the following forms:" + +#, no-wrap +msgid "" +"<h1><a name=\"\">Title</a></h1>\n" +"<h1><a href=\"\">Title</a></h1>\n" +"<h1><a name=\"\" href=\"\">Title</a></h1>" +msgstr "" +"<h1><a name=\"\">Title</a></h1>\n" +"<h1><a href=\"\">Title</a></h1>\n" +"<h1><a name=\"\" href=\"\">Title</a></h1>" + +msgid "" +"In these constructions, the heading level may vary from h1 to h6 " +"but the heading content (e.g., “Title”) must not be empty." +msgstr "" +"In these constructions, the heading level may vary from h1 to h6 " +"but the heading content (e.g., “Title”) must not be empty." + +msgid "" +"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." +msgstr "" +"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." + +msgid "" +"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." +msgstr "" +"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." + +msgid ".sh" +msgstr ".sh" + +msgid "Provides maintenance tasks for Bash scripts." +msgstr "Provides maintenance tasks for Bash scripts." + +msgid "" +"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.," +msgstr "" +"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.," + +msgid "" +"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 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." +msgstr "" +"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 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." + +msgid "Top-comment convention used by tuneup module." +msgstr "Top-comment convention used by tuneup module." + +#, no-wrap +msgid "" +"#!/bin/bash\n" +"######################################################################\n" +"#\n" +"# ${FILE}.sh -- ${DESCRIPTION}\n" +"#\n" +"# Written by:\n" +"#\n" +"######################################################################" +msgstr "" +"#!/bin/bash\n" +"######################################################################\n" +"#\n" +"# ${FILE}.sh -- ${DESCRIPTION}\n" +"#\n" +"# Written by:\n" +"#\n" +"######################################################################" + +msgid "Options" +msgstr "Options" + +msgid "--help" +msgstr "--help" + +msgid "Print module's documentation." +msgstr "Print module's documentation." + +msgid "--version" +msgstr "--version" + +msgid "Print module's version." +msgstr "Print module's version." + +msgid "--filter=\"REGEX\"" +msgstr "--filter=\"REGEX\"" + +msgid "" +"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." +msgstr "" +"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." + +msgid "Examples" +msgstr "Examples" + +msgid "centos-art.sh tuneup Automation/Scripts" +msgstr "centos-art.sh tuneup Automation/Scripts" + +msgid "" +"This command updates the top comment and variable name references " +"of all files inside the Automation/Scripts directory, recursively." +msgstr "" +"This command updates the top comment and variable name references " +"of all files inside the Automation/Scripts directory, recursively." + +msgid "centos-art.sh tuneup Automation/Scripts/tcar_printVersion.sh" +msgstr "centos-art.sh tuneup Automation/Scripts/tcar_printVersion.sh" + +msgid "" +"This commands updates the top comment and variable name references " +"inside the tcar_printVersion.sh file only." +msgstr "" +"This commands updates the top comment and variable name references " +"inside the tcar_printVersion.sh file only." + +msgid "" +"centos-art.sh tuneup Automation/Scripts --filter=\"tcar_print.+\\.sh" +"$\"" +msgstr "" +"centos-art.sh tuneup Automation/Scripts --filter=\"tcar_print.+\\.sh" +"$\"" + +msgid "" +"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." +msgstr "" +"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." + +msgid "Author" +msgstr "Author" + +msgid "" +"The tuneup module has received " +"contributions from the following people:" +msgstr "" +"The tuneup module has received " +"contributions from the following people:" + +msgid "" +"Alain Reguera Delgado, =COPYRIGHT_YEAR_FIRST=-=COPYRIGHT_YEAR_LAST=" +msgstr "" +"Alain Reguera Delgado, =COPYRIGHT_YEAR_FIRST=-=COPYRIGHT_YEAR_LAST=" + +msgid "Copyright" +msgstr "Copyright" + +msgid "" +"Copyright © =COPYRIGHT_YEAR_FIRST=-=COPYRIGHT_YEAR_LAST= " +"=COPYRIGHT_HOLDER=" +msgstr "" +"Copyright © =COPYRIGHT_YEAR_FIRST=-=COPYRIGHT_YEAR_LAST= " +"=COPYRIGHT_HOLDER=" + +msgid "" +"The tuneup module 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." +msgstr "" +"The tuneup module 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." + +msgid "" +"Tue tuneup module 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." +msgstr "" +"Tue tuneup module 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." + +msgid "" +"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." +msgstr "" +"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." + +msgid "See Also" +msgstr "See Also" + +msgid "centos-art.sh(1), xmllint(1)" +msgstr "centos-art.sh(1), xmllint(1)" + +#. Put one translator per line, in the form of NAME , YEAR1, YEAR2. +msgid "translator-credits" +msgstr "translator-credits" diff --git a/tcar-scripts-tuneup-docs/Manpages/render.conf b/tcar-scripts-tuneup-docs/Manpages/render.conf new file mode 100644 index 0000000..3694c89 --- /dev/null +++ b/tcar-scripts-tuneup-docs/Manpages/render.conf @@ -0,0 +1,7 @@ +[tuneup] +render-type = "asciidoc" +render-flow = "manpage" +render-from = "tuneup.asciidoc" +locale-from = "Locales/${TCAR_SCRIPT_LANG_LC}/tuneup.asciidoc.po" +formats = "xhtml manpage" +mansect = "1" diff --git a/tcar-scripts-tuneup-docs/Manpages/tuneup.asciidoc b/tcar-scripts-tuneup-docs/Manpages/tuneup.asciidoc new file mode 100644 index 0000000..bfe5edd --- /dev/null +++ b/tcar-scripts-tuneup-docs/Manpages/tuneup.asciidoc @@ -0,0 +1,198 @@ +tuneup(1) +========= + +Name +---- + +tuneup - Standardizes source code maintenance tasks inside the +repository. + +Synopsis +-------- + +*centos-art.sh tuneup [FILE ...|DIRECTORY ...] [--filter="REGEX"]*:: + Execute source code maintenance tasks. + +Description +----------- + +When you run the *tuneup* module 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 +<>. 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 <>). 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 centos-art.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: ++ +---------------------------------------------------------------------- +

Title

+

Title

+

Title

+---------------------------------------------------------------------- ++ +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 ++
+ 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 <> 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 +-------- + +*centos-art.sh tuneup Automation/Scripts*:: + This command updates the top comment and variable name references + of all files inside the Automation/Scripts directory, recursively. + +*centos-art.sh tuneup Automation/Scripts/tcar_printVersion.sh*:: + This commands updates the top comment and variable name references + inside the tcar_printVersion.sh file only. + +*centos-art.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 +------ + +The *tuneup* module has received contributions from the following +people: + + * mailto:al@centos.org.cu[Alain Reguera Delgado], =COPYRIGHT_YEAR_FIRST=-=COPYRIGHT_YEAR_LAST= + +[[copyright]] + +Copyright +--------- + +Copyright (C) =COPYRIGHT_YEAR_FIRST=-=COPYRIGHT_YEAR_LAST= =COPYRIGHT_HOLDER= + +The *tuneup* module 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. + +Tue *tuneup* module 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 +-------- + +centos-art.sh(1), xmllint(1) + +// vim: set syntax=asciidoc: