<section 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 id="cli_checkRepoDirSource" xreflabel="cli_checkRepoDirSource">cli_checkRepoDirSource

            <indexterm type="common-function" zone="cli_checkRepoDirSource">

            <primary>cli_checkRepoDirSource</primary>

            </indexterm>

            </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 id="cli_expandTMarkers" xreflabel="cli_expandTMarkers">cli_expandTMarkers

            <indexterm type="common-function" zone="cli_expandTMarkers">

                <primary>cli_expandTMarkers</primary>

            </indexterm>

            </command>

            <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. The

        <replaceable>LOCATION</replaceable> argument should point to

        the temporal file where translation markers expansion takes

        place in.

    </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 section 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

        section. 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>

    <para>

        See also: <xref linkend="cli_getTemporalFile" />

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term>

        <cmdsynopsis>

            <command id="cli_exportFunctions" xreflabel="cli_exportFuncations">cli_exportFunctions

            <indexterm type="common-function" zone="cli_exportFunctions">

                <primary>cli_exportFunctions</primary>

            </indexterm>

            </command>

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

        </cmdsynopsis>

    </term>

    <listitem>

    <para>

        The <function>cli_exportFunctions</function> function

        standardizes the way specific functionalities are exported to

        <command>centos-art.sh</command> script execution environment.

        The <replaceable>EXPORTID</replaceable> argument points the

        specific function initialization file relatively from

        <filename>trunk/Scripts/Bash/Functions</filename> directory

        on. For example, if we want to export the

        <function>render</function> specific functionality, we use the

        following construction:

    </para>

<programlisting>

cli_exportFunctions "Render/render"

</programlisting>

    <para>

        In this construction, <literal>Render</literal> with the first

        letter in upper case is the name of the directory under

        class="directory">trunk/Scripts/Bash/Functions</filename>

        where the specific functionality is stored in, and

        <literal>render</literal> with all letters in lower case is

        the name of the specific functionality we want to export,

        without its extension. This name is also used as suffix to

        identify all files related to the specific functionality we

        are exporting to <command>centos-art.sh</command> script

        execution environment.

    </para>

    <para>

        See also: <xref linkend="cli_unsetFunctions" />

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term>

        <cmdsynopsis>

        <command id="cli_getConfigLines" xreflabel="cli_getConfigLines">cli_getConfigLines

        <indexterm type="cli_getConfigLines" zone="cli_getConfigLines">

            <primary>cli_getConfigLines</primary>

        </indexterm>

        </command>

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

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

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

        </cmdsynopsis>

    </term>

    <listitem>

    <para>

        The <function>cli_getConfigLines</function> function

        standardizes the way configuration lines are retrieved from

        configuration files. 

    </para>

    <para>

        The <function>cli_getConfigLines</function> function accepts

        the following arguments:

    </para>

    <variablelist>

    <varlistentry>

    <term><replaceable>FILE</replaceable></term>

    <listitem>

    <para>

        This argument specifies the absolute path to the configuration

        file you want to retrieve configuration lines from. For

        example,

        <quote><filename>${TCAR_WORKDIR}/trunk/Identity/Models/Themes/Default/Distro/5/Anaconda/branding.conf</filename></quote>.

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term><replaceable>SECTION</replaceable></term>

    <listitem>

    <para>

        This argument specifies the name of the section you want to

        retrieve configuration lines from. For example,

        <quote>symbols</quote> without brackets.

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term><replaceable>OPTION</replaceable></term>

    <listitem>

    <para>

        This argument specifies the name of the option related to the

        configuration line you want to retrieve. For example,

        <quote>anaconda_header.svgz</quote>.

    </para>

    </listitem>

    </varlistentry>

    </variablelist>

    <para>

        In order for <function>cli_getConfigLines</function> to work

        properly, the configuration files must have a section line

        with the form <literal>[sectionname]</literal> which groups

        several <literal>option = "value"</literal> lines.

        Lines beginning with <literal>#</literal> are ignored and can

        be used for comments.

    </para>

    <example id="cli_getConfigLines-conffile">

    <title>Configuration file used to produce Tcar-fs documentation manual</title>

    <screenshot>

    <screeninfo>Configuration used to produce Tcar-fs documentation manual</screeninfo>

    <mediaobject>

    <textobject>

<programlisting>

[main]

# Specify documentation backend used by documentation manual.

manual_format = "texinfo"

# Specify title style used by sections inside the manual.

manual_section_style = "directory"

# Specify the order used by sections inside the manual.

manual_section_order = "ordered"

[templates]

# Specify relation between template files and section definition files

# inside the manual. 

Chapters/section-functions.texinfo   = "^.+-functions-[[:alnum:]]+\.texinfo$"

Chapters/section.texinfo             = "^.+\.texinfo$"

</programlisting>

</textobject>

</mediaobject>

</screenshot>

    </example>

    <para>

        The section names and option names used inside configuration

        files can be anything. It depends on the use and

        interpretation programmed inside

        <command>centos-art.sh</command> script for specific purposes

        which defines what kind of section and options must exist

        inside a configuration file. For example, consider the

        configuration files used by <function>render</function>

        functionality. They follow the same structure used in

        documentation configuration files but the meaning of their

        sections and options change to fit the specific needs of

        <function>render</function> functionality.

    </para>

    <example id="cli_getConfigLines-conffile-2">

    <title>Configuration file used to produced Anaconda images</title>

    <screenshot>

    <screeninfo>Configuration used to produced Anaconda images</screeninfo>

    <mediaobject>

    <textobject>

<programlisting>

[types]

anaconda_header.svgz   = "Types/White/48/=\BRAND=-5.png:x48+20+20"

first.svgz             = "Types/White/32/=\BRAND=-5.png:x32+30+219"

splash.svgz            = "Types/White/48/=\BRAND=-5-msg.png:x48+30+138"

[symbols]

anaconda_header.svgz   = "Symbols/48/=\BRAND=.png:x48+732+20"

first.svgz             = "Symbols/48/=\BRAND=.png:x48+30+20"

splash.svgz            = "Symbols/48/=\BRAND=.png:x48+30+20"

</programlisting>

</textobject>

</mediaobject>

</screenshot>

    </example>

    <para>

        Use the <function>cli_getConfigLines</function> function when

        you need to retrieve <literal>option = "value"</literal> lines

        from configuration files in a controlled way.

    </para>

    <para>

        See also: <xref linkend="cli_getConfigValue" />

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term>

        <cmdsynopsis>   

            <command id="cli_getConfigValue" xreflabel="cli_getConfigValue">cli_getConfigValue

            <indexterm type="common-function" zone="cli_getConfigValue">

                <primary>cli_getConfigValue</primary>

            </indexterm>

            </command>

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

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

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

        </cmdsynopsis>   

    </term>

    <listitem>

    <para>

        The <function>cli_getConfigValue</function> function

        standardizes the way option values are retrieved from

        configuration files. As convention,

        <function>cli_getConfigValue</function> uses the output

        produced by <function>cli_getConfigLines</function> as input

        to retrieve the option values. As convention, in

        <literal>option = "value"</literal> lines, the values

        retrieved are always on the right side. The values retrieved

        are also output without quotation and translation markers

        already expanded.

    </para>

    <para>

        The <function>cli_getConfigValue</function> function accepts

        the following arguments:

    </para>

    <variablelist>

    <varlistentry>

    <term><replaceable>FILE</replaceable></term>

    <listitem>

    <para>

        This argument specifies the absolute path to the configuration

        file you want to retrieve the value from. For example,

        <quote><filename>${TCAR_WORKDIR}/trunk/Identity/Models/Themes/Default/Distro/5/Anaconda/branding.conf</filename></quote>.

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term><replaceable>SECTION</replaceable></term>

    <listitem>

    <para>

        This argument specifies the name of the section related to the

        configuration line you want to retrieve the value from. For

        example, <quote>symbols</quote> without brackets.

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term><replaceable>OPTION</replaceable></term>

    <listitem>

    <para>

        This argument specifies the name of the option you want to

        retrieve the value from. For example, in 

        linkend="cli_getConfigLines-conffile-2" />, the

        <quote><literal>anaconda_header.svgz</literal></quote> option will output the

        <quote><literal>Symbols/48/=\BRAND=.png:x48+732+20</literal></quote> value

        without quotation and translation markers expanded. So if the

        value of <envar>TCAR_BRAND</envar> environment variable is

        <quote><literal>centos</literal></quote>, the real value you

        get will be

        <quote><literal>Symbols/48/centos.png:x48+732+20</literal></quote>.

    </para>

    </listitem>

    </varlistentry>

    </variablelist>

    <para>

        Use the <function>cli_getConfigValue</function> function

        whenever you want to retrieve values from configuration files

        in a controlled way.

    </para>

    <para>

        See also: <xref linkend="cli_getConfigLines" />

    </para>

    </listitem>

    </varlistentry>

    <varlistentry>

    <term>

        <cmdsynopsis>

            <command id="cli_getFilesList" xreflabel="cli_getFilesList">cli_getFilesList

            <indexterm type="common-function" zone="cli_getFilesList">

                <primary>cli_getFilesList</primary>

            </indexterm>

            </command>

            <arg choice="opt">--pattern</arg>

            <arg choice="opt">--mindepth</arg>

            <arg choice="opt">--maxdepth</arg>

            <arg choice="opt">--type</arg>

            <arg choice="opt">--uid</arg>

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

        </cmdsynopsis>

    </term>

    <listitem>

    <para>

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

        list of files are built inside the

        <command>centos-art.sh</command> script. This function outputs

        a sorted and unique list of files based on the options and

        location provided as argument. This function is an interface

        to the <command>find</command> command. Don't use

        <command>find</command> command directly inside the

        centos-art.sh script. Instead, use the

        <function>cli_getFilesList</function> function.

    </para>

    <para>

        The <function>cli_getFilesList</function> accepts the

        following arguments:

    </para>

    <variablelist>

    <varlistentry>

    <term><replaceable>LOCATION</replaceable></term>

    <listitem>

    <para>

        This arguments must be the absolute path to a directory and

        specifies where the search of files in any form (e.g.,

        directories, links, etc.) will take place in. If

        <replaceable>LOCATION</replaceable> isn't a directory, the

        script finishes its execution with an error message.

    </para>

    </listitem>