From be6bef07debeb0fefb0172ab4833002aaeec401d Mon Sep 17 00:00:00 2001 From: Alain Reguera Delgado Date: Nov 03 2010 20:17:09 +0000 Subject: Update documentation manuals. Working on trunk/Scripts/Bash/Functions.texi. --- diff --git a/Manuals/en/Html/Repository/repository.html b/Manuals/en/Html/Repository/repository.html index 36ee93f..8dcbe28 100644 --- a/Manuals/en/Html/Repository/repository.html +++ b/Manuals/en/Html/Repository/repository.html @@ -13,7 +13,7 @@ Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled GNU Free Documentation License. --> - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + $MESSAGE + + `AsRequestLine' + To standardize request messages using one-column format. + Request messages supress the trailing newline character from + final output. + $MESSAGE + + `AsYesOrNoRequestLine' + To standardize `yes or no' request messages using one-column + format. If something different from `y' is answered (when + using `en_US.UTF-8' locale), script execution ends immediatly. + + + $MESSAGE [y/N]: + + When you are using `centos-art.sh' script in a locale + different from `en_US.UTF-8', confirmation answer may be + different from `y'. For example, if you are using + `es_ES.UTF-8' locale, the confirmation question would look + like: + + + $MESSAGE [s/N]: + + and the confirmation answer would be `s', as it is on Spanish + `sí' word. + + Definition of which confirmation word to use is set on + translation messages for your specific locale information. + *Note trunk Scripts Bash Functions Locale::, for more + information about locale-specific translation messages. + + `AsToKnowMoreLine' + To standardize `to know more, run the following command:' + messages. When the `AsToKnowMoreLine' option is used, the + MESSAGE value should be set to `"$(caller)"'. `caller' is a + Bash builtin that returns the context of the current + subroutine call. `AsToKnowMoreLine' option uses `caller' + builtin output to build documentation entry dynamically. + + + ---------------------------------------------------------------------- + To know more, run the following command: + centos-art help --read='path/to/dir' + ---------------------------------------------------------------------- + + Use `AsToKnowMoreLine' option after errors and for intentional + script termination. + + `AsRegularLine' + To standardize regular messages using one-column format. + + When MESSAGE contains a colon inside (e.g., `description: + message'), the `cli_printMessage' function outputs MESSAGE + using two-columns format. + + Two-columns format definition is taken from + `trunk/Scripts/Bash/Styles/output_forTwoColumns.awk' file. 3.35.3.3 Specific functions ........................... @@ -4599,90 +4810,90 @@ documentation entry (*note trunk Translations::). Index ***** -branches: See 1. (line 369) -Common translation files: See 3.48.2.5. (line 4024) -How to render brands' translation files: See 3.50.3. (line 4329) -How to render fonts' translation files: See 3.52.3. (line 4406) -How to render translation files: See 3.48.3. (line 4194) -Specific translation files: See 3.48.2.6. (line 4049) -tags: See 2. (line 372) -Template translation files: See 3.48.2.4. (line 3854) -Translation brands file names: See 3.50.2.1. (line 4286) -Translation configuration scripts: See 3.48.2.8. (line 4083) -Translation entries: See 3.48.2.1. (line 3670) -Translation files: See 3.48.2.3. (line 3786) -Translation markers: See 3.48.2.2. (line 3751) -Translation paths: See 3.48.2.1. (line 3670) +branches: See 1. (line 368) +Common translation files: See 3.48.2.5. (line 4235) +How to render brands' translation files: See 3.50.3. (line 4540) +How to render fonts' translation files: See 3.52.3. (line 4617) +How to render translation files: See 3.48.3. (line 4405) +Specific translation files: See 3.48.2.6. (line 4260) +tags: See 2. (line 371) +Template translation files: See 3.48.2.4. (line 4065) +Translation brands file names: See 3.50.2.1. (line 4497) +Translation configuration scripts: See 3.48.2.8. (line 4294) +Translation entries: See 3.48.2.1. (line 3881) +Translation files: See 3.48.2.3. (line 3997) +Translation markers: See 3.48.2.2. (line 3962) +Translation paths: See 3.48.2.1. (line 3881) Translation pre-rendering configuration scripts:See 3.48.2.8. - (line 4083) -Translation rendering: See 3.48.2.7. (line 4072) -Translation rendering default functionality: See 3.48.2.9. (line 4169) -trunk: See 3. (line 375) -trunk Identity: See 3.1. (line 378) -trunk Identity Brands: See 3.2. (line 798) -trunk Identity Fonts: See 3.3. (line 815) -trunk Identity Icons: See 3.4. (line 891) -trunk Identity Isolinux: See 3.5. (line 908) -trunk Identity Models: See 3.6. (line 925) -trunk Identity Models Css: See 3.7. (line 945) -trunk Identity Models Html: See 3.8. (line 967) -trunk Identity Models Img Promo Web: See 3.9. (line 988) -trunk Identity Models Tpl: See 3.10. (line 1009) -trunk Identity Models Tpl Promo Web: See 3.11. (line 1030) -trunk Identity Models Xcf: See 3.12. (line 1344) -trunk Identity Release: See 3.13. (line 1365) -trunk Identity Themes: See 3.14. (line 1382) -trunk Identity Themes Models: See 3.15. (line 1407) -trunk Identity Themes Models Alternative: See 3.16. (line 1440) -trunk Identity Themes Models Default: See 3.17. (line 1467) -trunk Identity Themes Models Default Distro: See 3.18. (line 1499) + (line 4294) +Translation rendering: See 3.48.2.7. (line 4283) +Translation rendering default functionality: See 3.48.2.9. (line 4380) +trunk: See 3. (line 374) +trunk Identity: See 3.1. (line 377) +trunk Identity Brands: See 3.2. (line 797) +trunk Identity Fonts: See 3.3. (line 814) +trunk Identity Icons: See 3.4. (line 890) +trunk Identity Isolinux: See 3.5. (line 907) +trunk Identity Models: See 3.6. (line 924) +trunk Identity Models Css: See 3.7. (line 944) +trunk Identity Models Html: See 3.8. (line 966) +trunk Identity Models Img Promo Web: See 3.9. (line 987) +trunk Identity Models Tpl: See 3.10. (line 1008) +trunk Identity Models Tpl Promo Web: See 3.11. (line 1029) +trunk Identity Models Xcf: See 3.12. (line 1343) +trunk Identity Release: See 3.13. (line 1364) +trunk Identity Themes: See 3.14. (line 1381) +trunk Identity Themes Models: See 3.15. (line 1406) +trunk Identity Themes Models Alternative: See 3.16. (line 1439) +trunk Identity Themes Models Default: See 3.17. (line 1466) +trunk Identity Themes Models Default Distro: See 3.18. (line 1498) trunk Identity Themes Models Default Distro Anaconda:See 3.19. - (line 1583) -trunk Identity Themes Models Default Promo: See 3.20. (line 1600) -trunk Identity Themes Models Default Web: See 3.21. (line 1626) -trunk Identity Themes Motifs: See 3.22. (line 1651) -trunk Identity Themes Motifs Modern Backgrounds:See 3.23. (line 1755) + (line 1582) +trunk Identity Themes Models Default Promo: See 3.20. (line 1599) +trunk Identity Themes Models Default Web: See 3.21. (line 1625) +trunk Identity Themes Motifs: See 3.22. (line 1650) +trunk Identity Themes Motifs Modern Backgrounds:See 3.23. (line 1754) trunk Identity Themes Motifs Modern Backgrounds Img:See 3.24. - (line 1877) + (line 1876) trunk Identity Themes Motifs Modern Backgrounds Tpl:See 3.25. - (line 1898) + (line 1897) trunk Identity Themes Motifs Modern Backgrounds Xcf:See 3.26. - (line 1919) + (line 1918) trunk Identity Themes Motifs Modern Distro Anaconda Progress:See 3.27. - (line 1946) -trunk Identity Themes Motifs Modern Palettes: See 3.28. (line 2002) -trunk Identity Themes Motifs TreeFlower: See 3.29. (line 2024) + (line 1945) +trunk Identity Themes Motifs Modern Palettes: See 3.28. (line 2001) +trunk Identity Themes Motifs TreeFlower: See 3.29. (line 2023) trunk Identity Themes Motifs TreeFlower Backgrounds:See 3.30. - (line 2041) -trunk Identity Widgets: See 3.31. (line 2337) -trunk Manuals: See 3.32. (line 2354) -trunk Scripts: See 3.33. (line 2408) -trunk Scripts Bash: See 3.34. (line 2432) -trunk Scripts Bash Functions: See 3.35. (line 2544) -trunk Scripts Bash Functions Help: See 3.36. (line 2926) -trunk Scripts Bash Functions Html: See 3.37. (line 2947) -trunk Scripts Bash Functions Locale: See 3.38. (line 2968) -trunk Scripts Bash Functions Path: See 3.39. (line 3048) -trunk Scripts Bash Functions Render: See 3.40. (line 3082) -trunk Scripts Bash Functions Render Config: See 3.41. (line 3103) -trunk Scripts Bash Functions Shell: See 3.42. (line 3281) -trunk Scripts Bash Functions Svg: See 3.43. (line 3302) -trunk Scripts Bash Functions Verify: See 3.44. (line 3346) -trunk Scripts Bash Locale: See 3.45. (line 3554) -trunk Scripts Perl: See 3.46. (line 3583) -trunk Scripts Python: See 3.47. (line 3600) -trunk Translations: See 3.48. (line 3621) -trunk Translations Identity: See 3.49. (line 4224) -trunk Translations Identity Brands: See 3.50. (line 4245) -trunk Translations Identity Brands Tpl: See 3.51. (line 4340) -trunk Translations Identity Fonts: See 3.52. (line 4355) -trunk Translations Identity Models: See 3.53. (line 4422) -trunk Translations Identity Release: See 3.54. (line 4437) -trunk Translations Identity Themes: See 3.55. (line 4452) -trunk Translations Identity Themes Backgrounds:See 3.56. (line 4467) + (line 2040) +trunk Identity Widgets: See 3.31. (line 2336) +trunk Manuals: See 3.32. (line 2353) +trunk Scripts: See 3.33. (line 2407) +trunk Scripts Bash: See 3.34. (line 2431) +trunk Scripts Bash Functions: See 3.35. (line 2543) +trunk Scripts Bash Functions Help: See 3.36. (line 3137) +trunk Scripts Bash Functions Html: See 3.37. (line 3158) +trunk Scripts Bash Functions Locale: See 3.38. (line 3179) +trunk Scripts Bash Functions Path: See 3.39. (line 3259) +trunk Scripts Bash Functions Render: See 3.40. (line 3293) +trunk Scripts Bash Functions Render Config: See 3.41. (line 3314) +trunk Scripts Bash Functions Shell: See 3.42. (line 3492) +trunk Scripts Bash Functions Svg: See 3.43. (line 3513) +trunk Scripts Bash Functions Verify: See 3.44. (line 3557) +trunk Scripts Bash Locale: See 3.45. (line 3765) +trunk Scripts Perl: See 3.46. (line 3794) +trunk Scripts Python: See 3.47. (line 3811) +trunk Translations: See 3.48. (line 3832) +trunk Translations Identity: See 3.49. (line 4435) +trunk Translations Identity Brands: See 3.50. (line 4456) +trunk Translations Identity Brands Tpl: See 3.51. (line 4551) +trunk Translations Identity Fonts: See 3.52. (line 4566) +trunk Translations Identity Models: See 3.53. (line 4633) +trunk Translations Identity Release: See 3.54. (line 4648) +trunk Translations Identity Themes: See 3.55. (line 4663) +trunk Translations Identity Themes Backgrounds:See 3.56. (line 4678) trunk Translations Identity Themes Distro Anaconda Progress:See 3.57. - (line 4488) -trunk Translations Identity Widgets: See 3.58. (line 4581) + (line 4699) +trunk Translations Identity Widgets: See 3.58. (line 4792) List of Figures *************** diff --git a/Manuals/en/Texinfo/Repository/trunk/Scripts/Bash/Functions.texi b/Manuals/en/Texinfo/Repository/trunk/Scripts/Bash/Functions.texi index 848e46f..f12535c 100644 --- a/Manuals/en/Texinfo/Repository/trunk/Scripts/Bash/Functions.texi +++ b/Manuals/en/Texinfo/Repository/trunk/Scripts/Bash/Functions.texi @@ -32,8 +32,8 @@ functionalities already available don't do what you exactly expect, contact their authors and work together to improve them. @quotation -@strong{Tip} Most debates about CentOS Artwork Repository take place -in the CentOS art works (@email{centos-art@@centos.org}) mailing list. +@strong{Tip} Join CentOS developers mailing list +(@email{centos-devel@@centos.org}) to share your ideas. @end quotation It is also worth to know what global functions we have available, so @@ -41,14 +41,13 @@ advantage can be taken from them. Global functions are stored immediatly under @file{trunk/Scripts/Bash/Functions} directory in files begining with @samp{cli} prefix. -@subsubsection Creating new specific functionalities - OK, let's begin with our specific functionality example. -What function name do we use? Well, lets use @samp{greet}. Note that +What function name do we use? Well, lets use @code{greet}. Note that @samp{hello} is not a verb, but an expression, a kind of greeting, an -interjection specifically. In contrast, @samp{greet} is a verb and +interjection specifically. In contrast, @code{greet} is a verb and describes what we do when we say @samp{Hello!}, @samp{Hi!}, and so on. + So far, we've gathered the following function information: @verbatim @@ -63,14 +62,14 @@ function path, function script, and function definition inside function script. @end quotation -As consistency convenction, files related to @samp{greet} +As consistency convenction, files related to @code{greet} functionality are stored under its own function path. The @file{greet.sh} function script is the first file @file{centos-art.sh} -script loads when the @samp{greet} functionality is called using +script loads when the @code{greet} functionality is called using commands like @samp{centos-art greet --hello='World'}. -The @file{greet.sh} function script contains the @command{greet} -function definition. Inside @file{centos-art.sh} script, each function +The @file{greet.sh} function script contains the @code{greet} function +definition. Inside @file{centos-art.sh} script, each function definition has its own top commentary, followed by one blank line, and then one function defintion below it. @@ -78,9 +77,10 @@ The function top commentary contains a brief description about what the function does, one-line for copyright note ---with your personal information---, the license under which the function source code is released ---the @file{centos-art.sh} script is released as GPL, so do -all its functions---, and the subversion @samp{$Id$} keyword. In our -function example, the @file{greet.sh} top commentary would look like -the following: +all its functions---, and the subversion @code{$Id$} keyword---which +is later expanded when we do @command{svn propset} over +@file{greet.sh} file---. In our function example, the @file{greet.sh} +top commentary would look like the following: @verbatim #!/bin/bash @@ -89,7 +89,7 @@ the following: # your screen. Use this function to understand how centos-art.sh # script specific functionalities work. # -# Copyright (C) 2010 Alain Reguera Delgado +# Copyright (C) YEAR YOURFULLNAME # # 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 @@ -107,17 +107,17 @@ the following: # USA. # # ---------------------------------------------------------------------- -# $Id: greet.sh 520 2010-11-02 09:44:26Z al $ +# $Id$ # ---------------------------------------------------------------------- @end verbatim -The @samp{greet} function defines variables that will be available -along @samp{greet} function execution environment. Later, as final -definition, the @samp{greet} function calls the +The @code{greet} function defines variables that will be available +along @code{greet} function execution environment. Later, as final +definition, the @code{greet} function calls the @file{greet_getActions} function defined inside @file{greet_getActions.sh} function script. -In our example, the @samp{greet} function definition would look as +In our example, the @code{greet} function definition would look as follows: @verbatim @@ -131,16 +131,15 @@ function greet { } @end verbatim -This time we didn't use global variables for @option{greet} -functionality, so we left section for global variables definition -empty. +This time we didn't use global variable definitions for @code{greet} +execution environment, so we left the section empty. -The @command{greet_getActions} function defines the command-line -interface of @option{greet} functionality. The command-line interface +The @code{greet_getActions} function defines the command-line +interface of @code{greet} functionality. The command-line interface defines what to do with arguments passed to @file{centos-art.sh} -script once @option{greet} has been specified as second argument. +script once @code{greet} has been specified as second argument. -In our function example, the @command{greet_getActions} function +In our function example, the @code{greet_getActions} function definition would look like the following: @verbatim @@ -180,11 +179,11 @@ Of course, function documentation needs to be created first task is something you ---as author of specific functions--- probably want to do personally. -Following with our example, the @command{greet_doHello}, and -@command{greet_doBye} functions are the core of @option{greet} -specific functionality. In such functions is where we define what our -function realy does ---output different kinds of greetings, in the -sake of our example---. +Following with our example, the @code{greet_doHello}, and +@code{greet_doBye} function definitions are the core of @code{greet} +specific functionality. In such function definitions is where we +define what our function realy does ---output different kinds of +greetings, in the sake of our example---. @verbatim function greet_doHello { @@ -194,6 +193,9 @@ function greet_doHello { } @end verbatim +The @code{greet_doHello} function definition is stored in +@file{greet_doHello.sh} function script. + @verbatim function greet_doBye { @@ -202,17 +204,24 @@ function greet_doBye { } @end verbatim -In both @command{greet_doHello} and @command{gree_doBye} function -definitions, we used the @var{OPTIONVAL} variable. This variable is -defined in @file{cli.sh} function script and contains the value passed -after the equal sign (i.e., @samp{=}) inside second command-line -argument. For example, if the second command-line argument is -@option{--hello='World'}, the value of @var{OPTIONVAL} variable is -@samp{World} without quotes. +The @code{greet_doBye} function definition is stored in the +@file{greet_doBye.sh} function script. + +Both @file{greet_doHello.sh} and @file{greet_doBye.sh} function +scripts are stored inside @code{greet}'s function directory path (i.e. +@file{trunk/Scripts/Bash/Functions/Greet}). + +In the examples above, we use the @var{OPTIONVAL} global variable. +The @var{OPTIONVAL} variable is defined in @file{cli.sh} function +script and contains the value passed after the equal sign (i.e., +@samp{=}) in the second command-line argument of @file{centos-art.sh} +script. For example, if the second command-line argument is +@option{--hello='World'}, the value of @var{OPTIONVAL} variable would +be @samp{World} without quotes. -Well, it seems that our example is rather complete by now. Let's see -how its files are organized. For this, we use the @command{tree} -command: +Let's see how @code{greet} specific functionality files are organzied +under @code{greet}'s function directory. To see file organization, we +use the @command{tree} command: @verbatim trunk/Scripts/Bash/Functions/Greet @@ -222,10 +231,10 @@ trunk/Scripts/Bash/Functions/Greet `-- greet.sh @end verbatim -To try the @option{greet} specific functionality, you need to pass the -@option{greet} as first argument to @file{centos-art.sh} script, and -any of the valid options as second argument. Some examples are -illustrated below: +To try the @code{greet} specific functionality, pass @code{greet} +string as first argument to @file{centos-art.sh} script, and any of +the valid options as second argument. Some examples are illustrated +below: @verbatim [centos@projects ~]$ centos-art greet --hello='World' @@ -236,9 +245,21 @@ Goodbye World @end verbatim The word @samp{World} in the examples above, can be anything. In fact, -change it to have a little fun :). +change it to have a little fun :). + +Now that we have a specific function that works as we expect, it is +time to document it. To document @code{greet} specific functionality, +we need to use its directory path and the @code{help} functionality +(@pxref{trunk Scripts Bash Functions Help}) of @file{centos-art.sh} +script, just as the following command illustrates: + +@verbatim +centos-art help --edit=trunk/Scripts/Bash/Functions/Greet +@end verbatim + +Well, it seems that our example is rather complete by now. -In @option{greet} example we've described so far, we only use the +In @code{greet} example we've described so far, we only use the @command{cli_printMessage} global function in action specific functions, but more interesting things can be achieved inside them. For example, if you pass a directory path as second argument option @@ -252,7 +273,7 @@ specific functionalities work inside @file{centos-art.sh} script. With some of luck this introduction will also serve you as motivation to create your own specific functionalities. -By the way, the @option{greet} functionality doesn't exist inside +By the way, the @code{greet} functionality doesn't exist inside @file{centos-art.sh} script. Would you like to create it? @subsection Usage @@ -262,34 +283,38 @@ By the way, the @option{greet} functionality doesn't exist inside The following global variables of @file{centos-art.sh} script, are available for you to use inside specific functions: -@table @var -@item TEXTDOMAIN +@defvar TEXTDOMAIN Default domain used to retrieve translated messages. This value is set in `initFunctions.sh' and shouldn't be changed. +@end defvar -@item TEXTDOMAINDIR +@defvar TEXTDOMAINDIR Default directory used to retrieve translated messages. This value is set in `initFunctions.sh' and shouldn't be changed. +@end defvar -@item ACTION +@defvar ACTION Default action passed to @command{centos-art} command as first argument. For example, in the command @samp{centos-art render --entry=path/to/dir --filter=regex}, the action passed to @command{centos-art} is @option{render}. +@end defvar -@item OPTIONNAM +@defvar OPTIONNAM Default option name passed to @command{centos-art} command as second argument. For example, in the command @samp{centos-art render --entry=path/to/dir --filter=regex}, the option name passed to @command{centos-art} as second argument is @option{--entry}. +@end defvar -@item OPTIONVAL +@defvar OPTIONVAL Default option value passed to @command{centos-art} command as second argument. For example, in the command @samp{centos-art render --entry=path/to/dir --filter=regex}, the option value passed to @command{centos-art} as second argument is @option{path/to/dir}. +@end defvar -@item REGEX +@defvar REGEX Default option value passed to @command{centos-art} command as third argument. For example, in the command @samp{centos-art render --entry=path/to/dir --filter=regex}, the option value passed to @@ -301,20 +326,23 @@ name is stocked to @option{--filter} for whatever value it passed at the right side of its equal sign. Generally, third argument option value is used to pass regular expression patterns that modify the list of files to process but this is not the only feature it may serve to. +@end defvar -@item ANSWER +@defvar ANSWER Default answer for questions. As most questions are to request confirmation about some specific action, default answer to this variable is negative (i.e., @samp{No}). Default answer value takes place when no value is entered as response to confirmation questions before pressing @key{RET} key. +@end defvar -@item TMPFILE +@defvar TMPFILE Default location to store temporal files. This variable contains a value with the format @samp{/tmp/centos-art-$$}. The @samp{$$} expands to the process id of @command{centos-art} current execution. +@end defvar -@item EDITOR +@defvar EDITOR Default text editor. This variable contains the absolute path to @file{centos-art.sh} script default text editor (i.e., @file{/usr/bin/vim}). If you want to use a different text editor set, @@ -327,65 +355,294 @@ editors only: @item /usr/bin/emacs @item /usr/bin/nano @end itemize - -@end table +@end defvar @subsubsection Global functions The following global functions of @file{centos-art.sh} script, are available for you to use inside specific functions: -@table @command -@item cli_checkFiles -This function checks files (e.g., regular files, regular directories, -symbolic links, etc.) existence. +@defun cli_commitRepoChanges +The @code{cli_commitRepoChanges} function uses the list of files +stored in the @var{FILES} variable and verifies changes inside your +repository working copy, using subversion commands. If +@code{cli_commitRepoChanges} finds changes inside your working copy, +it asks you for confirmation to commit them up to central repository. + +Call @code{cli_commitRepoChanges} function after functions that modify +files inside your repository working copy. + +@end defun + +@defun cli_checkFiles FILE [TYPE [ACTION [OPTIONS]]] +@code{cli_checkFiles} receives a @var{FILE} absolute path and performs +verification as specified in @var{TYPE}. + +When @var{TYPE} is not specified, @code{cli_checkFiles} verifies +@var{FILE} existence, no matter what kind of file it be. If +@var{TYPE} is specified, it can take one of the following values: + +@table @option +@item d +@itemx directory +To evaluate @var{FILE} as directory. +@item f +@item regular-file +To evaluate @var{FILE} as regular file. +@item h +@itemx symbolic-link +To evaluate @var{FILE} as symbolic link. +@item fh +To evaluate @var{FILE} as regular file first and symbolic link later. +When @var{FILE} is neither a regular file or a symbolic link, +@code{cli_checkFiles} considers @var{FILE} as unexistent file. +@end table -@item cli_getCountryCodes -This function outputs a list with country codes as defined in ISO3166 -standard. +When @var{ACTION} is not specified, @code{cli_checkFiles} function uses +@samp{Checking} as default action message. The action message is used +on left-column as description for verification action. It may be cases +where you need to change default action message with your own. In that +cases remember to use the @code{"`gettext "Your message"`"} +construction in order for @command{gettext} to know about it. This way +your action message can be translated to other languages too. + +By default @code{cli_checkFiles} output information about @var{FILE} +on the right column. When @var{OPTIONS} is specified, default behaivour +is modified as specified in @var{OPTIONS}. The @var{OPTIONS} can take +any of the following options: +@table @option + +@item --quiet +If this option is specified, @code{cli_checkFiles} supresses +verification output. This option is useful if you only want to do +file verifications but don't want to output any information about it. -@item cli_getCountryNames -This function reads one language locale code in the format LL_CC and -outputs the name of its related country. +@verbatim +cli_checkFiles $FILE 'f' '' '--quiet' +if [[ $? -eq 0 ]];then + echo "File exists." +else + echo "File doesn't exist" +fi +@end verbatim +@end table +@end defun + +@defun cli_getCountryCodes [FILTER] +@code{cli_getCountryCodes} function outputs a list with country codes +as defined in ISO3166 standard. When @var{FILTER} is provided, +@code{cli_getCountryCodes} outpus country codes that match +@var{FILTER} regular expression pattern. +@end defun + +@defun cli_getCountryNames [FILTER] +@code{cli_getCountryNames} function reads one language locale code in +the format LL_CC and outputs the name of its related country as in +ISO3166. If filter is specified, just the country name that matches +@var{FILTER}, exactly, is returned. +@end defun -@item cli_getCurrentLocale -This function checks @var{LANG} environment variable and returns the -current locale from more specific to less specific. For example, if -the locale @samp{en_GB} is the current one, it should be used instead -of just @samp{en}. - -@item cli_getLangCodes -This function outputs a list of language codes as defined in ISO639 -standard. - -@item cli_getLangNames -This function reads one language locale code in the format LL_CC and -outputs its language name as defined in ISO639 standard. - -@item cli_getLocales -This function outputs locale codes in LL and LL_CC format. Combine -both ISO639 and ISO3166 specification in order to build the final -locale list. This function defines which translation locales are -supported inside CentOS Artwork Repository. - -@item cli_getRepoNames -This function sets naming convenction. Inside CentOS Artowrk -Repository, regular files are written in lower case and directories -are written in lower case but with the first letter in upper case. Use -this function to sanitate the name of regular files and directories -you work with. - -@item cli_getThemeName -This function manipulates the current absolute path to extract the -theme name from it. If there is no theme in the path, this function -returns an empty string. - -@item cli_printMessage -This function outputs information in predifined formats. This function -(cli_printMessage) is the standard way to output information inside -@file{centos-art.sh} script. Use this function whenever you need to -output information from @file{centos-art.sh}. +@defun cli_getCurrentLocale +@code{cli_getCurrentLocale} function checks @var{LANG} environment +variable and returns the current locale from more specific to less +specific. For example, if the locale @samp{en_GB} is the current one, +it should be used instead of just @samp{en}. +@end defun + +@defun cli_getLangCodes [FILTER] +@code{cli_getLangCodes} function outputs a list of language codes as +defined in ISO639 standard. When @var{FILTER} is provided, +@code{cli_getLangCodes} outputs language codes that match @var{FILTER} +regular expression pattern. +@end defun + +@defun cli_getLangNames +@code{cli_getLangNames} function reads one language locale code in the +format LL_CC and outputs its language name as defined in ISO639 +standard. If filter is specified, just the language name that matches +@var{FILTER}, exactly, is returned. +@end defun + +@defun cli_getLocales +@code{cli_getLocales} function outputs locale codes in LL and LL_CC +format. Combine both ISO639 and ISO3166 specification in order to +build the final locale list. The @code{cli_getLocales} function +defines which translation locales are supported inside CentOS Artwork +Repository. +@end defun + +@defun cli_getRepoNames +@code{cli_getRepoNames} function sets naming convenction inside CentOS +Artowrk Repository. As convenction, regular files are written in lower +case and directories are written in CamelCase. Use this function to +sanitate the name of regular files and directories you work with. +@end defun + +@defun cli_getThemeName +@code{cli_getThemeName} function manipulates the current absolute path +to extract the theme name from it. If there is no theme in the path, +this function returns an empty string. +@end defun + +@defun cli_printMessage MESSAGE [FORMAT] +@code{cli_printMessage} function outputs information in predifined +formats. The @code{cli_printMessage} function is the standard way to +output information inside @file{centos-art.sh} script. Use this +function whenever you need to output information from +@file{centos-art.sh}. + +When @var{FORMAT} is not specified, @code{cli_printMessage} outputs +information just as it was passed in @var{MESSAGE} variable. +Otherwise, @var{FORMAT} can take one of the following values: + +@table @option +@item AsHeadingLine +To standardize heading messages. +@verbatim +---------------------------------------------------------------------- +$MESSAGE +---------------------------------------------------------------------- +@end verbatim + +@item AsWarningLine +To standardize warning messages. +@verbatim +---------------------------------------------------------------------- +WARNING: $MESSAGE +---------------------------------------------------------------------- +@end verbatim + +@item AsNoteLine +To standardize note messages. +@verbatim +---------------------------------------------------------------------- +NOTE: $MESSAGE +---------------------------------------------------------------------- +@end verbatim + +@item AsUpdatingLine +To standardize @samp{Updating} messages using two-columns format. +@verbatim +Updating $MESSAGE +@end verbatim + +@item AsRemovingLine +To standardize @samp{Removing} messages using two-columns format. +@verbatim +Removing $MESSAGE +@end verbatim + +@item AsCheckingLine +To standardize @samp{Checking} messages using two-columns format. +@verbatim +Checking $MESSAGE +@end verbatim + +@item AsCreatingLine +To standardize @samp{Creating} messages using two-columns format. +@verbatim +Creating $MESSAGE +@end verbatim + +@item AsSavedAsLine +To standardize @samp{Saved as} messages using two-columns format. +@verbatim +Saved as $MESSAGE +@end verbatim + +@item AsLinkToLine +To standardize @samp{Linked to} messages using two-columns format. +@verbatim +Linked to $MESSAGE +@end verbatim + +@item AsMovedToLine +To standardize @samp{Moved to} messages using two-columns format. +@verbatim +Moved to $MESSAGE +@end verbatim + +@item AsTranslationLine +To standardize @samp{Translation} messages using two-columns format. +@verbatim +Translation $MESSAGE +@end verbatim + +@item AsConfigurationLine +To standardize @samp{Configuration} messages using two-columns format. +@verbatim +Configuration $MESSAGE +@end verbatim + +@item AsResponseLine +To standardize response messages using one-column format. +@verbatim +--> $MESSAGE +@end verbatim + +@item AsRequestLine +To standardize request messages using one-column format. Request +messages supress the trailing newline character from final output. +@verbatim +$MESSAGE +@end verbatim + +@item AsYesOrNoRequestLine +To standardize @samp{yes or no} request messages using one-column +format. If something different from @samp{y} is answered (when using +@code{en_US.UTF-8} locale), script execution ends immediatly. + +@verbatim +$MESSAGE [y/N]: +@end verbatim + +When you are using @file{centos-art.sh} script in a locale different +from @code{en_US.UTF-8}, confirmation answer may be different from +@samp{y}. For example, if you are using @code{es_ES.UTF-8} locale, the +confirmation question would look like: + +@verbatim +$MESSAGE [s/N]: +@end verbatim + +and the confirmation answer would be @samp{s}, as it is on Spanish +@samp{sí} word. + +Definition of which confirmation word to use is set on translation +messages for your specific locale information. @xref{trunk Scripts +Bash Functions Locale}, for more information about locale-specific +translation messages. + +@item AsToKnowMoreLine + +To standardize @samp{to know more, run the following command:} +messages. When the @option{AsToKnowMoreLine} option is used, the +@var{MESSAGE} value should be set to @code{"$(caller)"}. @code{caller} +is a Bash builtin that returns the context of the current subroutine +call. @option{AsToKnowMoreLine} option uses @code{caller} builtin +output to build documentation entry dynamically. + +@verbatim +---------------------------------------------------------------------- +To know more, run the following command: +centos-art help --read='path/to/dir' +---------------------------------------------------------------------- +@end verbatim + +Use @option{AsToKnowMoreLine} option after errors and for intentional +script termination. + +@item AsRegularLine +To standardize regular messages using one-column format. + +When @var{MESSAGE} contains a colon inside (e.g., @samp{description: +message}), the @code{cli_printMessage} function outputs @var{MESSAGE} +using two-columns format. + +Two-columns format definition is taken from +@file{trunk/Scripts/Bash/Styles/output_forTwoColumns.awk} file. @end table +@end defun @subsubsection Specific functions