<sect1 id="scripts-bash-funref">

    <title>Environment Functions Reference</title>

    <para>

        In addition to environment variables described above, the

        centos-art.sh script makes available the following common

        environment functions once it is executed:

    </para>

    <variablelist>

    <varlistentry>

    <term>

        <cmdsynopsis>

            <command>cli_checkFiles</command> 

            <arg choice="req">

            <arg>-d</arg>

            <arg>-e</arg>

            <arg>-f</arg>

            <arg>-h</arg>

            <arg>-x</arg>

            </arg>

            <arg choice="req" rep="repeat"><replaceable>LOCATION</replaceable></arg>

        </cmdsynopsis>

    </term>

    <listitem>

    <para>

        The <function>cli_checkFiles</function> standardizes the way

        files are verified inside the centos-art.sh script. It tries

        to answers questions like <emphasis>Is

        <replaceable>LOCATION</replaceable> a regular file or

        directory?</emphasis> or even, <emphasis>does

        <replaceable>LOCATION</replaceable> have execution

        rights?</emphasis>.  You can provide several

        <replaceable>LOCATION</replaceable> arguments to this function

        in order to perform the verifications over them. Likewise, you

        can combine different options to realize different

        verifications over the same files. In case the verification

        fails, an error message is printed and the script finishes its

        execution.

    </para>

    <para>

        The <function>cli_checkFiles</function> is an interface for

        the <command>test</command> command and accepts the following

        options:

    </para>

    <variablelist>

    <varlistentry>

    <term><option>-d</option></term>

    <listitem>

    <para>

        Verifies whether <replaceable>LOCATION</replaceable> exists

        and is a directory. If it doesn't exists or isn't a directory,

        an error message is printed and the script finishes its

        execution.  Otherwise, if it exists and is a directory, the

        script continues its execution normally.

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term><option>-e</option></term>

    <listitem>

    <para>

        Verifies whether <replaceable>LOCATION</replaceable> exists or

        not. If it doesn't exist, an error message is printed and the

        script finishes its execution.  Otherwise, if it does exists,

        the script continues its execution normally.

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term><option>-f</option></term>

    <listitem>

    <para>

        Verifies whether <replaceable>LOCATION</replaceable> exists

        and is a regular file. If it doesn't exists or isn't a regular

        file, an error message is printed and the script finishes its

        execution. Otherwise, if it exists and is a regular file, the

        script continues its execution normally.

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term><option>-h</option></term>

    <listitem>

    <para>

        Verifies whether <replaceable>LOCATION</replaceable> exists

        and is a symbolic link. If it doesn't exists or isn't a

        symbolic link, an error message is printed and the script

        finishes its execution immediately.  Otherwise, if it does

        exist and is a symbolic link, the script continue its

        execution normally.

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term><option>-x</option></term>

    <listitem>

    <para>

        Verifies whether <replaceable>LOCATION</replaceable> exists

        and execution permission is granted. If it doesn't exist or

        hasn't execution permission, the script finishes its execution

        immediately. Otherwise, if it exists and has execution

        permissions, the script continues its execution normally.

    </para>

    </listitem>

    </varlistentry>

    </variablelist>

    <para>

        Use the <function>cli_checkFiles</function> function whenever

        you need to verify files inside the &TCAR;.

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term>

        <cmdsynopsis>

            <command>cli_checkRepoDirSource</command>

        </cmdsynopsis>

    </term>

    <listitem>

    <para>

        The <function>cli_checkRepoDirSource</function> function

        standardizes the path construction to directories inside it

        the working copy, using absolute paths.  This function

        transforms relative paths passed as non-option arguments to

        <command>centos-art.sh</command> script command-line into

        absolute paths inside the working copy and verifies whether

        they really exist as directories inside the working copy or

        not. If the path provided doesn't exist as directory inside

        the working copy, the script will finish its execution

        immediately with an error message. Otherwise, if the directory

        exists, the variable <varname>ACTIONVAL</varname> is redefined

        with the related absolute path for further use.

    </para>

    <para>

        Use the <function>cli_checkRepoDirSource</function> function

        whenever you need to be sure that non-option arguments passed

        to <command>centos-art.sh</command> script command-line will

        always point to directories inside the working copy.

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term>

        <cmdsynopsis>

            <command>cli_expandTMarkers</command>

            <arg choice="opt">--as-html-link</arg>

            <arg choice="opt">--with-locale</arg>

            <arg choice="req"><replaceable>LOCATION</replaceable></arg>

        </cmdsynopsis>

    </term>

    <listitem>

    <para>

        The <function>cli_expandTMarkers</function> standardizes

        construction of translation markers and their related

        expansion. As convention, translation markers are set inside

        source files (e.g., DocBook, SVG) and expanded inside temporal

        instances used to produce final contents.

    </para>

    <para>

        Translation markers written in source files must comply the

        <literal>=[A-Z_]+=</literal> regular expression pattern. For

        example, <literal>=UNKNOWN_MARKER=</literal> is a valid

        translation marker without any replacement. To prevent

        <command>centos-art.sh</command> script from expanding

        translation markers, add a backslash (<literal>\</literal>)

        between the first equal sign and the following letter. For

        example, <literal>=\...=</literal> won't be expanded.

    </para>

    <para>

        The <function>cli_expandTMarkers</function> supports the

        following translation markers:

    </para>

    <variablelist>

    <varlistentry>

    <term><literal>=\COPYRIGHT_YEAR_LAST=</literal></term>

    <term><literal>=\COPYRIGHT_YEAR=</literal></term>

    <listitem>

    <para>

        These translation markers expand to the last year used in

        copyright notes. For example,

        <literal>=COPYRIGHT_YEAR_LAST=</literal>. 

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term><literal>=\COPYRIGHT_YEAR_LIST=</literal></term>

    <term><literal>=\COPYRIGHT_YEARS_LIST=</literal></term>

    <listitem>

    <para>

        This translation markers expand to the list of years used in

        copyright notes. For example,

        <literal>=COPYRIGHT_YEARS_LIST=</literal>.  The first year

        represents the time we began to work on &TCAR;.

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term><literal>=\COPYRIGHT_HOLDER=</literal></term>

    <listitem>

    <para>

        This translation marker expands to the holder used in

        copyright notes. For example,

        <literal>=COPYRIGHT_HOLDER=</literal>.

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term><literal>=\COPYRIGHT_HOLDER_PREDICATE=</literal></term>

    <listitem>

    <para>

        This translation marker expands both the holder and the

        predicate used in copyright notes. For example,

        <literal>=COPYRIGHT_HOLDER_PREDICATE=</literal>.

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term><literal>=\BRAND=</literal></term>

    <listitem>

    <para>

        This translation marker expands to the brand name used on

        files names and URLs inside &TCAR;.  For example,

        <literal>=BRAND=</literal>.

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term><literal>=\LICENSE=</literal></term>

    <listitem>

    <para>

        This translation marker expands to the license information

        used in files created by <command>centos-art.sh</command>

        script. For example, <literal>=LICENSE=</literal>.

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term><literal>=\LICENSE_URL=</literal></term>

    <listitem>

    <para>

        This translation marker expands to the license URL used in

        files created by <command>centos-art.sh</command> script. For

        example, <literal>=LICENSE_URL=</literal>.

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term><literal>=\THEME=</literal></term>

    <listitem>

    <para>

        This translation marker expands to the theme portion of path

        you are producing through centos-art.sh script. As

        consequence, this translation marker should be used in

        situations where you are producing theme components only.

        This translation marker expands its value by retrieving the

        theme part of the path you provide as non-option argument to

        <command>centos-art.sh</command> script. For example, if you

        provide the path

        <filename>trunk/Identity/Images/Themes/Modern/2/Distro/5</filename>,

        this translation will expand to the

        <literal>Modern/2/</literal> value.

    </para>

    <para>

        In case you need to retrieve the theme name or version

        separately one another, then you can use the

        <literal>=\THEMENAME=</literal> and

        <literal>=\THEMERELEASE=</literal> translation markers,

        respectively. When you use these translation markers, forward

        slashes are removed from result. So, if you provide the path

        <filename>trunk/Identity/Images/Themes/Modern/2/Distro/5</filename>,

        <literal>=\THEMENAME=</literal> will expand to

        <literal>Modern</literal> and

        <literal>=THEMERELEASE=</literal> will expand to

        <literal>2</literal>.

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term><literal>=\RELEASE=</literal></term>

    <listitem>

    <para>

        This translation marker expands to the current release

        information of your CentOS distribution. By default this

        information is retrieved from

        <filename>/etc/redhat-release</filename>. In case the option

        <option>--release</option> be passed, the value specified with

        it will overwrite the default value and will be this the one

        used as reference for this translation marker to retrieve the

        release information. So, for example, if you are running a

        CentOS-5.8 distribution and no <option>--release</option>

        option is passed to <command>centos-art.sh</command> script,

        this translation marker expands to <literal>5.8</literal>. On

        the other hand, if you are still running a CentOS-5.8

        distribution but provide the <option>--release=6.3</option>

        option to <command>centos-art.sh</command> script, this

        translation marker expands to <literal>6.3</literal> instead.

    </para>

    <para>

        In case you need to retrieve minor and major release numbers

        separately one another, then you can use the

        <literal>=\MINOR_RELEASE=</literal> and

        <literal>=\MAJOR_RELEASE=</literal> translation makers,

        respectively.

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term><literal>=\ARCH=</literal></term>

    <listitem>

    <para>

        This translation marker expands to the current architecture of

        your CentOS Distribution. By default this information is

        retrieved from <command>uname -i</command>. In case the option

        <option>--arch</option> be passed, the value specified with it

        will overwrite the default value and will be the one used as

        reference. For example, if the <command>uname -i</command>

        outputs the line <computeroutput>i386</computeroutput>, this

        translation marker will expand to <literal>i386</literal>. On

        the other hand, if you pass the <option>--arch=x86_64</option>

        option to <command>centos-art.sh</command> script, this

        translation marker will expand to <literal>x86_64</literal>

        instead.

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term><literal>=\URL=</literal></term>

    <listitem>

    <para>

        This translation marker expands to the URL which points to

        &TC;; home page. For example, <literal>=URL=</literal>.  In

        case you are using the centos-art.sh script in a different

        locale but English (<literal>en_US.UTF-8</literal>), this

        translation marker expands as usual but with the language

        information appended to the end of the string. For example, if

        you are executing the centos-art.shscript for Spanish locale

        (e.g., <literal>es_ES.UTF-8</literal>), this translation

        marker expands to <literal>=URL=es/</literal>.

    </para>

    <para>

        In case you need to expand other URL related to &TC;; domain,

        use translation markers described in 

        linkend="scripts-bash-funref-expandTMarkers-Url" />. Likewise

        =\URL=, translation markers described in 

        linkend="scripts-bash-funref-expandTMarkers-Url" /> does

        append the current language information to the end of the URL

        string based on the locale information you are currently

        executing the <command>centos-art.sh</command> script.

    </para>

    <title>URL-related translation markers</title>

    <tgroup cols="2" align="left">

        <row>

            <entry>Translation Marker</entry>

            <entry>Expands To</entry>

        </row>

        <row>

            <entry><literal>=\URL_WIKI=</literal></entry>

            <entry><literal>=URL_WIKI=</literal></entry>

        </row>

        <row>

            <entry><literal>=\URL_LISTS=</literal></entry>

            <entry><literal>=URL_LISTS=</literal></entry>

        </row>

        <row>

            <entry><literal>=\URL_FORUMS=</literal></entry>

            <entry><literal>=URL_FORUMS=</literal></entry>

        </row>

        <row>

            <entry><literal>=\URL_MIRRORS=</literal></entry>

            <entry><literal>=URL_MIRRORS=</literal></entry>

        </row>

        <row>

            <entry><literal>=\URL_DOCS=</literal></entry>

            <entry><literal>=URL_DOCS=</literal></entry>

        </row>

        <row>

            <entry><literal>=\URL_PROJECTS=</literal></entry>

            <entry><literal>=URL_PROJECTS=</literal></entry>

        </row>

        <row>

            <entry><literal>=\URL_SVN=</literal></entry>

            <entry><literal>=URL_SVN=</literal></entry>

        </row>

        <row>

            <entry><literal>=\URL_TRAC=</literal></entry>

            <entry><literal>=URL_TRAC=</literal></entry>

        </row>

        <row>

            <entry><literal>=\URL_PLANET=</literal></entry>

            <entry><literal>=URL_PLANET=</literal></entry>

        </row>

    </tgroup>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term><literal>=\MAIL_DOCS=</literal></term>

    <listitem>

    <para>

        This translation marker expands to CentOS documentation

        mailing list address. For example,

        <literal>=MAIL_DOCS=</literal>.

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term><literal>=\LOCALE=</literal></term>

    <listitem>

    <para>

        This translation marker expands to the current locale

        information used by <command>centos-art.sh</command> script.

        This value is retrieved from the <envar>LANG</envar>

        environment variable and should look like

        <literal>=LOCALE=</literal>.  In case you need to retrieve the

        language and country part separately one another, you can use

        the <literal>=\LOCALE_LL=</literal> and

        <literal>=\LOCALE_CC=</literal>, respectively.

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term><literal>=\REPO_TLDIR=</literal></term>

    <listitem>

    <para>

        This translation marker expands to the absolute path to

        <filename class="directory">trunk/</filename> directory inside

        your workstation. For example,

        <literal>/home/al/Projects/CentOS/artwork/trunk</literal>.

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term><literal>=\REPO_HOME=</literal></term>

    <term><literal>=\TCAR_WORKDIR=</literal></term>

    <listitem>

    <para>

        This translation marker expands to the absolute path of your

        working copy.  For example,

        <literal>/home/al/Projects/CentOS/artwork</literal>.

    </para>

    </listitem>

    </varlistentry>

    </variablelist>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term>

        <cmdsynopsis>

            <command>cli_exportFunctions</command>

            <arg choice="req"><replaceable>EXPORTID</replaceable></arg>

        </cmdsynopsis>

    </term>

    <listitem>

    <para>

        ...

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term>

        <cmdsynopsis>

            <command>cli_synchronizeRepoChanges</command>

            <arg choice="req"><replaceable>LOCATION</replaceable></arg>

        </cmdsynopsis>

    </term>

    <listitem>

    <para>

        The <function>cli_synchronizeRepoChanges</function>

        standardizes the way changes are synchronized between the

        working copy and the central repository using

        <replaceable>LOCATION</replaceable> as reference. This

        function is the interface we use inside the

        <command>centos-art.sh</command> script to execute the

        <function>Svn</function> functionality described in 

        linkend="scripts-bash-svn" />.

    </para>

    <para>

        Use <function>cli_synchronizeRepoChanges</function> function

        inside the <command>centos-art.sh</command> script whenever

        you need to synchronize one or more changes at any

        <replaceable>LOCATION</replaceable> inside the working copy.

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term>

        <cmdsynopsis>

            <command>cli_printMessage</command>

            <arg choice="req"><replaceable>MESSAGE</replaceable></arg>

            <group choice="opt">

            <arg>--as-separator-line</arg>

            <arg>--as-banner-line</arg>

            <arg>--as-cropping-line</arg>

            <arg>--as-tuningup-line</arg>

            <arg>--as-checking-line</arg>

            <arg>--as-combining-line</arg>

            <arg>--as-creating-line</arg>

            <arg>--as-reading-line</arg>

            <arg>--as-savedas-line</arg>

            <arg>--as-linkto-line</arg>

            <arg>--as-movedto-line</arg>

            <arg>--as-validating-line</arg>

            <arg>--as-template-line</arg>

            <arg>--as-configuration-line</arg>

            <arg>--as-palette-line</arg>

            <arg>--as-reponse-line</arg>

            <arg>--as-request-line</arg>

            <arg>--as-selection-line</arg>

            <arg>--as-error-line</arg>

            <arg>--as-toknowmore-line</arg>

            <arg>--as-yesornorequest-line</arg>

            <arg>--as-notrailingnew-line</arg>

            <arg>--as-stdout-line</arg>

            <arg>--as-stderr-line</arg>

            </group>

        </cmdsynopsis>

    </term>

    <listitem>

    <para>

        The <function>cli_printMessage</function> function

        standardizes the way centos-ar.sh scirpt prints messages. By

        default, centos-art.sh script prints all messages to the

        standard output with the exception of those messages printed

        with the <option>--as-stderr-line</option> option, which are

        printed to standard error output instead.

    </para>

    <para>

        The <function>cli_printMessage</function> function requires

        two arguments.  The first argument specifies the

        <replaceable>MESSAGE</replaceable> you want to print and the

        second argument specifies the FORMAT you'll use to print that

        message. Because this function is so used inside the

        centos-art.sh script, it is convenient to provide localization

        to strings passed as <replaceable>MESSAGE</replaceable> using

        <command>gettext</command> contructions when they aren't

        paths.

    </para>

    <para>

        The <function>cli_printMessage</function> function accepts the

        following formats as second argument:

    </para>

    <variablelist>

    <varlistentry>

    <term><option>--as-separator-line</option></term>

    <listitem>

    <para>

        This format takes the first character passed as

        <replaceable>MESSAGE</replaceable> and repeats it horizontally

        to build a separator line.  Use this format whenever you need

        to create a logical separation between different actions.

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term><option>--as-banner-line</option></term>

    <listitem>

    <para>

        This format takes the string passed as

        <replaceable>MESSAGE</replaceable> and puts it inside two

        horizontal separator lines. Use this format whenever you need

        to print header information for following lines.

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term><option>--as-cropping-line</option></term>

    <listitem>

    <para>

        This format is for two columns messages where

        <replaceable>MESSAGE</replaceable> generally refers to a file

        inside the repository.  Use this format whenever you need to

        imply the fact that certain file has been cropped.

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term><option>--as-tuningup-line</option></term>

    <listitem>

    <para>

        This format is for two columns messages where

        <replaceable>MESSAGE</replaceable>

        generally refers to a file inside the repository.  Use this

        format whenever you need to imply the fact that certain file

        has been tuned-up.

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term><option>--as-checking-line</option></term>

    <listitem>

    <para>

        This format is for two columns messages where

        <replaceable>MESSAGE</replaceable> generally refers to a file

        inside the repository.  Use this format whenever you need to

        imply the fact that certain file has been checked or verified

        (e.g., through <function>cli_checkFiles</function>

        functionality).

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term><option>--as-combining-line</option></term>

    <listitem>

    <para>

        This format is for two columns messages where

        <replaceable>MESSAGE</replaceable> generally refers to a file

        inside the repository.  Use this format whenever you need to

        imply the fact that certain file has been combined.

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term><option>--as-creating-line</option></term>

    <listitem>

    <para>

        This format is for two columns messages where

        <replaceable>MESSAGE</replaceable> generally refers to a file

        inside the repository.  Use this format whenever you need to

        imply the fact that certain file has been created.

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term><option>--as-reading-line</option></term>

    <listitem>

    <para>

        This format is for two columns messages where

        <replaceable>MESSAGE</replaceable> generally refers to a file

        inside the repository.  Use this format whenever you need to

        imply the fact that certain file has been read.

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term><option>--as-savedas-line</option></term>

    <listitem>

    <para>

        This format is for two columns messages where

        <replaceable>MESSAGE</replaceable> generally refers to a file

        inside the repository.  Use this format whenever you need to

        imply the fact that certain file has been saved.

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term><option>--as-linkto-line</option></term>

    <listitem>

    <para>

        This format is for two columns messages where

        <replaceable>MESSAGE</replaceable> generally refers to a file

        inside the repository.  Use this format whenever you need to

        imply the fact that certain file has been linked.

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term><option>--as-movedto-line</option></term>

    <listitem>

    <para>

        This format is for two columns messages where

        <replaceable>MESSAGE</replaceable> generally refers to a file

        inside the repository.  Use this format whenever you need to

        imply the fact that certain file has been moved.

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term><option>--as-validating-line</option></term>

    <listitem>

    <para>

        This format is for two columns messages where