Blob Blame History Raw
<refentry id="scripts-bash-render">

    <refmeta>
        <refentrytitle>render</refentrytitle>
        <indexterm type="specific-function">
            <primary>Standardize rendition tasks inside &TCAR;.</primary>
        </indexterm>
    </refmeta>

    <refnamediv>
        <refname>render</refname>
        <refpurpose>Standardize rendition tasks inside &TCAR;.</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
    <cmdsynopsis>
        <command>centos-art</command>
        <arg choice="req">render</arg>
        <arg>-h|--help</arg>
        <arg>-q|--quiet</arg>
        <arg>--filter="<replaceable>REGEX</replaceable>"</arg>
        <arg>--answer-yes</arg>
        <arg>--dont-dirspecific</arg>
        <arg>--releasever="<replaceable>RELEASEVER</replaceable>"</arg>
        <arg>--basearch="<replaceable>BASEARCH</replaceable>"</arg>
        <arg>--post-rendition="<replaceable>COMMAND</replaceable>"</arg>
        <arg>--last-rendition="<replaceable>COMMAND</replaceable>"</arg>
        <arg>--theme-model="<replaceable>MODELNAME</replaceable>"</arg>
        <arg>--with-brands</arg>
        <arg>--synchronize</arg>
        <arg choice="req" rep="repeat"><replaceable>LOCATION</replaceable></arg>
    </cmdsynopsis>
    </refsynopsisdiv>

    <refsection id="scripts-bash-render-description">
    <title>Description</title>

    <para>
        The <function>render</function> functionality exists to
        automate content rendition inside &TCAR;. The content
        rendition process itself takes place through the following
        rendition modes:
    </para>

    <itemizedlist>
    <listitem>
    <para>
        <literal>svg</literal> &mdash; This modes works with both
        gzip-compressed (<filename class="extension">.svgz</filename>)
        or uncompressed (<filename class="extension">.svg</filename>)
        scalable vector graphics as source files and produces portable
        network graphics as main output.
    </para>
    </listitem>
    <listitem>
    <para>
        <literal>docbook</literal> &mdash; This mode works with
        DocBook source files and produces XHTML as main output. It is
        also possible to produce PDF output from DocBook source files,
        however PDF output is commented because its production fails
        trying to create indexes.
    </para>
    </listitem>
    <listitem>
    <para>
        <literal>conf</literal> &mdash; This mode works with one or
        more configuration files as source and produces portable
        network graphics as main output. The format used in these
        configuration files is described in <xref
        linkend="scripts-bash-render-description-conffiles"/>.
    </para>
    </listitem>
    </itemizedlist>

    <para>
        To determine the rendition mode, the
        <function>render</function> functionality uses the path
        provided as <replaceable>LOCATION</replaceable> argument and
        the path name convention described in <xref
        linkend="repo-convs-relbdirs" />.
    </para>

    <refsection id="scripts-bash-render-description-renderabledirs">
    <title>Render-able Directories</title>

    <para>
        The render-able directories are conventional locations inside
        the working copy where you can find final output files. The
        final output files are produced from source files and
        auxiliary files.  Auxiliary files are frequently used to
        create localized instances of source files which are, in turn,
        used to create final output files in different forms (e.g., in
        a different language).
    </para>

    <para>
        Inside the working copy of &TCAR;, the following directory
        structures are considered render-able directories:
    </para>

    <itemizedlist>
    <listitem>
    <para>
        <filename class="directory">Identity/Images/</filename>
        &mdash; This directory structure organizes final image files
        in different formats. It also includes source files for
        producing the backgrounds of themes. Related design models for
        all these files are under <filename
        class="directory">Identity/Models/</filename> directory
        structure.
    </para>
    <important>
    <para>
        Don't move any source file related to theme backgrounds from
        render-able directories to theme design models directory
        structure.  The source files related to theme backgrounds are
        specific to each theme and cannot be shared among different
        themes. The directory structure related to theme design models
        is reserved for files shared by all themes.
    </para>
    </important>
    </listitem>
    <listitem>
    <para>
        <filename
        class="directory">Documentation/Manuals/</filename>
        &mdash; This directory structure organizes final documentation
        files. Design models for all these files are organized under
        <filename
        class="directory">Documentation/Models/</filename>
        directory structure.
    </para>
    </listitem>
    </itemizedlist>

    <para>
        Inside render-able directories the rendition process is
        performed through different rendition flows known as
        theme-rendition, base-rendition, post-rendition and
        last-rendition.
    </para>
    </refsection>

    <refsection id="scripts-bash-render-description-themeflow">
    <title>Theme-Rendition Flow</title>
    <para>
        The theme-rendition flow exists to produce content inside
        <filename>Identity/Images/Themes/</filename> directory
        structure. This rendition flow identifies which directories
        are render-able and uses the base-rendition on them, one by
        one.
    </para>
    <para>
        The theme-rendition flow exists to support massive rendition
        of themes through the following command:
    </para>

    <cmdsynopsis>
        <command>centos-art render Identity/Images/Themes</command>
    </cmdsynopsis>

    <para>
        In case you need to limit the amount of themes or components
        inside themes you want to render, you can be more
        specific about the <replaceable>LOCATION</replaceable> you
        passed as argument and use the
        <option>--filter="<replaceable>REGEX</replaceable>"</option>
        to specify the file you want to render.  For example, if you
        only want to render the <filename>01-welcome.png</filename>
        Anaconda file for CentOS-5 distribution based on version 2 of
        Modern artistic motif, then you can run the following command:
    </para>

    <cmdsynopsis>
        <command>centos-art render Identity/Images/Themes/Modern/2/Distro/5/Anaconda --filter="01-welcome"</command>
    </cmdsynopsis>

    <para>
        Notice that you can reach the same result in different ways
        here by creating combinations between the path you provide as
        <replaceable>LOCATION</replaceable> and the
        <option>--filter</option> option. For example, the following
        commands produce the same result:
    </para>

    <cmdsynopsis>
        <command>centos-art render Identity/Images/Themes/Modern/2/Distro/5/Anaconda</command>
    </cmdsynopsis>

    <cmdsynopsis>
        <command>centos-art render Identity/Images/Themes/Modern --filter="2/Distro/5/Anaconda"</command>
    </cmdsynopsis>

    <para>
        You can use whatever combination you like whenever it matches
        a valid render-able directory inside the working copy. But it
        seems to be an acceptable practice to use the
        <replaceable>LOCATION</replaceable> argument to specify the
        render-able directory path inside the <filename
        class="directory">Identity/Images/Themes</filename>
        directory which images need to be rendered for and the
        <option>--filter</option> option only when it is needed to
        restrict rendition to a specific file inside the directory
        provided as <replaceable>LOCATION</replaceable>.
    </para>

    </refsection>

    <refsection id="scripts-bash-render-description-baseflow">
    <title>Base-Rendition Flow</title>
    <para>
        ...
    </para>
    </refsection>

    <refsection id="scripts-bash-render-description-postflow">
    <title>Post-Rendition Flow </title>
    <para>
        ...
    </para>
    </refsection>

    <refsection id="scripts-bash-render-description-lastflow">
    <title>Last-Rendition Flow </title>
    <para>
        ...
    </para>
    </refsection>

    <refsection id="scripts-bash-render-description-conffiles">
    <title>Configuration Files (<filename>render.conf</filename>)</title>
    <para>
        ...
    </para>
    </refsection>
    </refsection>

    <refsection id="scripts-bash-render-usage">
    <title>Usage</title>
    <para>
        ...
    </para>
    </refsection>

    <refsection id="scripts-bash-render-option">
    <title>Options</title>

    <para>
        The <command>centos-art prepare</command> command accepts
        common options described in <xref
        linkend="scripts-bash-cli-commonoptions" /> and the following
        specific options:
    </para>

    <variablelist>

    <varlistentry>
    <term><option>--answer-yes</option></term>
    <listitem>
    <para>
       Assume <emphasis>yes</emphasis> to all confirmation requests.
    </para>
    </listitem>
    </varlistentry>

    <varlistentry>
    <term><option>--filter="<replaceable>REGEX</replaceable>"</option></term>
    <listitem>
    <para>
        This option reduces the list of files to process inside
        <replaceable>LOCATION</replaceable> using
        <replaceable>REGEX</replaceable> as <replaceable>REGUEX</replaceable>
        using <replaceable>REGEX</replaceable> as files you want to render.
        The deeper you go into the directory structure the more
        specific you'll be about the files you want to render.  When
        you cannot go deeper into the directory structure through
        <replaceable>LOCATION</replaceable> specification, use this
        option to reduce the list of files therein.
    </para>
    </listitem>
    </varlistentry>

    <varlistentry>
    <term><option>--synchronize</option></term>
    <listitem>
    <para>
        Synchronizes available changes between the working copy and
        the central repository.
    </para>
    </listitem>
    </varlistentry>

    <varlistentry>
    <term><option>--releasever="<replaceable>RELEASE</replaceable>"</option></term>
    <listitem>
    <para>
        This option expands the <code>=\RELEASE=</code>,
        <code>=\MAJOR_RELEASE=</code>, and
        <code>=\MINOR_RELEASE=</code> translation makers based on
        <replaceable>NUMBER</replaceable> value.  Notice that
        translation markers here were escaped using a backslash
        (<code>\</code>) in order to prevent their expansion. Use this
        option when you need to produce release-specific contents, but
        no release information can be retrived from the directory path
        you are currently rendering.
    </para>
    </listitem>
    </varlistentry>

    <varlistentry>
    <term><option>--basearch="<replaceable>BASEARCH</replaceable>"</option></term>
    <listitem>
    <para>
        This option expands the <code>=\ARCHITECTURE=</code>,
        translation makers based on <replaceable>ARHC</replaceable> value.
        Notice that translation markers here were escaped using a
        backslash (<code>\</code>) in order to prevent their
        expansion. Use this option when you need to produce
        architecture-sepecific contents but no architecture
        information can be retrived from the directory path you are
        currently rendering.
    </para>
    </listitem>
    </varlistentry>

    <varlistentry>
    <term><option>--theme-model="<replaceable>MODELNAME</replaceable>"</option></term>
    <listitem>
    <para>
        This option specifies the name of theme model you want to use
        when producing theme artistic motifs. By default, if this
        option is not provided, the <literal>Default</literal> theme
        model is used as reference to produce theme artistic motifs.
        To know what values can be passed as
        <replaceable>MODELNAME</replaceable>, run the following
        command:
    </para>

    <cmdsynopsis>
        <command>ls ${TCAR_WORKDIR}/Identity/Models/Themes</command>
    </cmdsynopsis>

    </listitem>
    </varlistentry>

    <varlistentry>
    <term><option>--post-rendition="<replaceable>COMMAND</replaceable>"</option></term>
    <listitem>
    <para>
        This option lets you apply a command as post-rendition action.
        In this case, the <replaceable>COMMAND</replaceable>
        represents the command-line you want to execute in order to
        perform in-place modifications to base-rendition output.
    </para>
    </listitem>
    </varlistentry>

    <varlistentry>
    <term><option>--last-rendition="<replaceable>COMMAND</replaceable>"</option></term>
    <listitem>
    <para>
        This option lets you apply a command as last-rendition action.
        In this case, the <replaceable>COMMAND</replaceable> argument
        represents the command string you want to execute in order to
        perform in-place modifications to base-rendition,
        post-rendition and directory-specific rendition outputs. 
    </para>
    </listitem>
    </varlistentry>
    </variablelist>
    </refsection>

    <refsection id="scripts-bash-render-examples">
    <title>Examples</title>
    <para>
        ...
    </para>
    </refsection>

    <refsection id="scripts-bash-render-bugs">
    <title>Bugs</title>
    <para>
        To report bugs related to this function, please create a new
        ticket <ulink
        url="https://projects.centos.org/trac/artwork/newticket?summary=Error%20Standardizing%20Rendition%20Tasks&amp;component=Scripts">here</ulink>
        refering the specific problems you found in it. For example,
        it would be useful if you copy and paste any error output from
        <command>centos-art.sh</command> script.
    </para>
    </refsection>

    <refsection id="scripts-bash-render-authors">
    <title>Authors</title>
    <para>
        The following people have worked in this functionality:
    </para>
    <itemizedlist>
    <listitem>
    <para>
        Alain Reguera Delgado &lt;<ulink url="mailto:alain.reguera@gmail.com">alain.reguera@gmail.com</ulink>&gt;, =COPYRIGHT_YEAR_LIST=
    </para>
    </listitem>
    </itemizedlist>
    </refsection>

    <refsection id="scripts-bash-render-licence">
    <title>License</title>

    <para>
        Copyright &copy; =COPYRIGHT_YEAR_LIST= The CentOS Project
    </para>
 
    <para>
        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 the Free Software Foundation; either version 2 of
        the License, or (at your option) any later version.
    </para>
 
    <para>
        This program is distributed in the hope that it will be
        useful, but WITHOUT ANY WARRANTY; without even the implied
        warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
        PURPOSE.  See the GNU General Public License for more details.
    </para>
 
    <para>
        You should have received a copy of the GNU General Public
        License along with this program; if not, write to the Free
        Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139,
        USA.
    </para>
    </refsection>

</refentry>