From 905b185545e2ab955413cb91fa304f997e711af3 Mon Sep 17 00:00:00 2001 From: Alain Reguera Delgado Date: Oct 06 2012 15:32:11 +0000 Subject: Add `Scripts/Bash/cliref.docbook' file. --- diff --git a/Documentation/Models/Docbook/Tcar-ug/Scripts/Bash/cliref.docbook b/Documentation/Models/Docbook/Tcar-ug/Scripts/Bash/cliref.docbook new file mode 100644 index 0000000..221c353 --- /dev/null +++ b/Documentation/Models/Docbook/Tcar-ug/Scripts/Bash/cliref.docbook @@ -0,0 +1,294 @@ +
+ + Command-line Reference + + + The centos-art.sh script follows a + conventional command-line interface where there might be + options and non-option arguments in it. As convention, the + first non-option argument passed to + centos-art.sh script will be the name of + the specific function you want to execute (e.g., + render, locale, + help, etc.). This first argument will be + immediately removed from the list of arguments passed to + centos-art.sh script to leave just the + remaining options and non-option arguments passed to it. At + this point, the centos-art.sh script uses + the getopt command to retrieve option + arguments and remove them from the list of arguments passed to + centos-art.sh script. + + + + Once option arguments have been removed from list of arguments + passed to centos-art.sh script, non option + arguments are processed then. Non-option arguments will + always be paths pointing directories inside your working copy + of &TCAR;. These paths can be absolute paths or relative paths + considering the working copy root directory as section. For + example, both the absolute path /home/al/Projects/CentOS/artwork/trunk/Identity/Themes/ + and the relative path trunk/Identity/Themes point to + the same location. + + +
+ The Command-line Interface + + + To better understand the centos-art.sh + command-line interface, let's consider the real command shown + in as + section. This command shows the entire command as a list of + space-separated arguments. The value of each argument can be + reached using special variable names based on the number of + arguments passed to the command-line. + + + + The command-line interface + + The command-line interface + + + + ${0} | |${1}| | ${2} | | ${3} | +---------|-|----|-|--------------------------|-|-----------| +centos-art render trunk/Identity/Images/Themes --with-brands +---------|-|----|-|--------------------------|-|-----------| + + + + + + + + In , the + relation between special variables and arguments has the + following meaning: + + + + + ${0} + + + This variable contains the absolute path to the command + executed. In case your home directory be /home/john the value of this + argument will be expanded to + /home/john/bin/centos-art which is a + symbolic link to the + ${TCAR_WORKDIR}/trunk/Scripts/Bash/centos-art.sh + file. + + + + + + ${1} + + + This variable contains the first non-option argument we use to + determine the specific function environment we want to execute + (e.g., render in this case). The position + of this information in the command-line is relevant to + centos-art.sh script and must not be + changed. Possible values to this variable are specified in + . + + + + + + + ${2} + + + This variable contains a non-option argument referring a path + information inside the working copy of &TCAR;. The specific + path information you provide in this variable must be + recognized by specific function environment provided in + ${1} variable. The position of path + information in the command-line is not relevant to + centos-art.sh script and can be changed + whenever it doesn't be interpreted as value to + ${1} variable. + + + + + + ${3} + + + This variable contains an option argument. The specific option + information you provide in this variable must be recognized by + specific function environment provided in + ${1} variable. The position of options in + the command-line is not relevant to + centos-art.sh script and can be changed + whenever it doesn't be interpreted as value to + ${1} variable. + + + + + +
+ +
+ Common Options + + + As convention, all function specific environments should + provide support for the following common options: + + + + + | + + + This option makes centos-art.sh script to + shows information about the specific function environment + (e.g., how to execute it, available options, etc.) set as + first non-option argument. For example, if you provide the + centos-art render --help, the + centos-art.sh script will display to you + the information related to the trunk/Scripts/Bash/Functions/Render + directory. + + + This information is retrived from The CentOS Artwork + Repository File System (tcar-fs) documentation manual. + This manual is written in Texinfo format and provides a quick + way for you to read and browse documentation related to each + directory inside &TCAR; as you work with it from a text + terminal. + + + + + + | + + + This option makes the centos-art.sh script + to suppress messages sent to standard output. This option + doesn't suppress error messages, nor questions related to + script execution. + + + + + +
+ +
+ Specific Options + + + The specific options used by specific and common function + environments are described in their respective sections. See + and to know which these + sections are. + + + + Specific Function Environments + + + + Name + Description + + + + + + prepare + + + + render + + + + locale + + + + help + + + + pack + + + + tuneup + + + + svn + + + + + +
+ + + Common Function Environments + + + + Name + Description + + + + + + cli_checkFiles + + + + + +
+ +
+ +
+ + Implementation + + + When a new function is created to + centos-art.sh script, it is necessary + to consider whether it will use arguments or not. When the + function doesn't need arguments (e.g., it exists to + redefine values related to global variables only) there is + no need to consider a parsing feature for it. However, + when the function does use arguments it is very important + to parse them appropriately (e.g., by using a parsing feature like + that provided by getopt command). + + + + In this section will describe how to parse arguments (both + option and non-option) inside the + centos-art.sh script. This information + must be used as section whenever you need to create a + new function for centos-art.sh script. + + +
+ +