Blame Documentation/Models/Docbook/Tcar-ug/Scripts/Bash/render.docbook

ed015e
<refentry id="scripts-bash-render">
0ace69
ed015e
    <refmeta>
ed015e
        <refentrytitle>render</refentrytitle>
ed015e
        <indexterm type="specific-function">
a491c8
            <primary>Standardize rendition tasks inside &TCAR;.</primary>
ed015e
        </indexterm>
ed015e
    </refmeta>
0ace69
ed015e
    <refnamediv>
ed015e
        <refname>render</refname>
0fe2f1
        <refpurpose>Standardize rendition tasks inside &TCAR;.</refpurpose>
ed015e
    </refnamediv>
0ace69
ed015e
    <refsynopsisdiv>
a491c8
    <cmdsynopsis>
a491c8
        <command>centos-art</command>
a491c8
        <arg choice="req">render</arg>
a491c8
        <arg>-h|--help</arg>
a491c8
        <arg>-q|--quiet</arg>
a491c8
        <arg>--filter="<replaceable>REGEX</replaceable>"</arg>
a491c8
        <arg>--answer-yes</arg>
a491c8
        <arg>--dont-dirspecific</arg>
a491c8
        <arg>--releasever="<replaceable>RELEASEVER</replaceable>"</arg>
a491c8
        <arg>--basearch="<replaceable>BASEARCH</replaceable>"</arg>
a491c8
        <arg>--post-rendition="<replaceable>COMMAND</replaceable>"</arg>
a491c8
        <arg>--last-rendition="<replaceable>COMMAND</replaceable>"</arg>
a491c8
        <arg>--theme-model="<replaceable>MODELNAME</replaceable>"</arg>
a491c8
        <arg>--with-brands</arg>
3b9515
        <arg>--synchronize</arg>
0fe2f1
        <arg choice="req" rep="repeat"><replaceable>LOCATION</replaceable></arg>
a491c8
    </cmdsynopsis>
ed015e
    </refsynopsisdiv>
6104cf
ed015e
    <refsection id="scripts-bash-render-description">
ed015e
    <title>Description</title>
6104cf
0ace69
    <para>
0fe2f1
        The <function>render</function> functionality exists to
0fe2f1
        automate content rendition inside &TCAR;. The content
0fe2f1
        rendition process itself takes place through the following
0fe2f1
        rendition modes:
0fe2f1
    </para>
0fe2f1
0fe2f1
    <itemizedlist>
0fe2f1
    <listitem>
0fe2f1
    <para>
0fe2f1
        <literal>svg</literal> — This modes works with both
0fe2f1
        gzip-compressed (<filename class="extension">.svgz</filename>)
0fe2f1
        or uncompressed (<filename class="extension">.svg</filename>)
0fe2f1
        scalable vector graphics as source files and produces portable
0fe2f1
        network graphics as main output.
0fe2f1
    </para>
0fe2f1
    </listitem>
0fe2f1
    <listitem>
0fe2f1
    <para>
0fe2f1
        <literal>docbook</literal> — This mode works with
0fe2f1
        DocBook source files and produces XHTML as main output. It is
0fe2f1
        also possible to produce PDF output from DocBook source files,
0fe2f1
        however PDF output is commented because its production fails
0fe2f1
        trying to create indexes.
0fe2f1
    </para>
0fe2f1
    </listitem>
0fe2f1
    <listitem>
0fe2f1
    <para>
0fe2f1
        <literal>conf</literal> — This mode works with one or
0fe2f1
        more configuration files as source and produces portable
0fe2f1
        network graphics as main output. The format used in these
0fe2f1
        configuration files is described in 
0fe2f1
        linkend="scripts-bash-render-description-conffiles"/>.
0fe2f1
    </para>
0fe2f1
    </listitem>
0fe2f1
    </itemizedlist>
0fe2f1
0fe2f1
    <para>
0fe2f1
        To determine the rendition mode, the
0fe2f1
        <function>render</function> functionality uses the path
0fe2f1
        provided as <replaceable>LOCATION</replaceable> argument and
0fe2f1
        the path name convention described in 
0fe2f1
        linkend="repo-convs-relbdirs" />.
0ace69
    </para>
0ace69
a491c8
    <refsection id="scripts-bash-render-description-renderabledirs">
0fe2f1
    <title>Render-able Directories</title>
a491c8
0ace69
    <para>
0fe2f1
        The render-able directories are conventional locations inside
0fe2f1
        the working copy where you can find final output files. The
0fe2f1
        final output files are produced from source files and
0fe2f1
        auxiliary files.  Auxiliary files are frequently used to
0fe2f1
        create localized instances of source files which are, in turn,
0fe2f1
        used to create final output files in different forms (e.g., in
0fe2f1
        a different language).
ed015e
    </para>
a491c8
ed015e
    <para>
a491c8
        Inside the working copy of &TCAR;, the following directory
a491c8
        structures are considered render-able directories:
ed015e
    </para>
ed015e
a491c8
    <itemizedlist>
a491c8
    <listitem>
a491c8
    <para>
47422e
        <filename class="directory">Identity/Images/</filename>
a491c8
        — This directory structure organizes final image files
a491c8
        in different formats. It also includes source files for
a491c8
        producing the backgrounds of themes. Related design models for
a491c8
        all these files are under 
47422e
        class="directory">Identity/Models/</filename> directory
a491c8
        structure.
a491c8
    </para>
a491c8
    <important>
a491c8
    <para>
a491c8
        Don't move any source file related to theme backgrounds from
a491c8
        render-able directories to theme design models directory
a491c8
        structure.  The source files related to theme backgrounds are
a491c8
        specific to each theme and cannot be shared among different
a491c8
        themes. The directory structure related to theme design models
a491c8
        is reserved for files shared by all themes.
a491c8
    </para>
a491c8
    </important>
a491c8
    </listitem>
a491c8
    <listitem>
ed015e
    <para>
a491c8
        
47422e
        class="directory">Documentation/Manuals/</filename>
a491c8
        — This directory structure organizes final documentation
a491c8
        files. Design models for all these files are organized under
a491c8
        
47422e
        class="directory">Documentation/Models/</filename>
a491c8
        directory structure.
ed015e
    </para>
a491c8
    </listitem>
a491c8
    </itemizedlist>
ed015e
0fe2f1
    <para>
0fe2f1
        Inside render-able directories the rendition process is
0fe2f1
        performed through different rendition flows known as
0fe2f1
        theme-rendition, base-rendition, post-rendition and
0fe2f1
        last-rendition.
0fe2f1
    </para>
0fe2f1
    </refsection>
0fe2f1
0fe2f1
    <refsection id="scripts-bash-render-description-themeflow">
0fe2f1
    <title>Theme-Rendition Flow</title>
0fe2f1
    <para>
0fe2f1
        The theme-rendition flow exists to produce content inside
47422e
        <filename>Identity/Images/Themes/</filename> directory
0fe2f1
        structure. This rendition flow identifies which directories
0fe2f1
        are render-able and uses the base-rendition on them, one by
0fe2f1
        one.
0fe2f1
    </para>
0fe2f1
    <para>
0fe2f1
        The theme-rendition flow exists to support massive rendition
0fe2f1
        of themes through the following command:
0fe2f1
    </para>
0fe2f1
0fe2f1
    <cmdsynopsis>
47422e
        <command>centos-art render Identity/Images/Themes</command>
0fe2f1
    </cmdsynopsis>
0fe2f1
0fe2f1
    <para>
0fe2f1
        In case you need to limit the amount of themes or components
0fe2f1
        inside themes you want to render, you can be more
0fe2f1
        specific about the <replaceable>LOCATION</replaceable> you
0fe2f1
        passed as argument and use the
0fe2f1
        <option>--filter="<replaceable>REGEX</replaceable>"</option>
0fe2f1
        to specify the file you want to render.  For example, if you
0fe2f1
        only want to render the <filename>01-welcome.png</filename>
0fe2f1
        Anaconda file for CentOS-5 distribution based on version 2 of
0fe2f1
        Modern artistic motif, then you can run the following command:
0fe2f1
    </para>
0fe2f1
0fe2f1
    <cmdsynopsis>
47422e
        <command>centos-art render Identity/Images/Themes/Modern/2/Distro/5/Anaconda --filter="01-welcome"</command>
0fe2f1
    </cmdsynopsis>
0fe2f1
0fe2f1
    <para>
0fe2f1
        Notice that you can reach the same result in different ways
0fe2f1
        here by creating combinations between the path you provide as
0fe2f1
        <replaceable>LOCATION</replaceable> and the
c1de68
        <option>--filter</option> option. For example, the following
c1de68
        commands produce the same result:
0fe2f1
    </para>
0fe2f1
0fe2f1
    <cmdsynopsis>
47422e
        <command>centos-art render Identity/Images/Themes/Modern/2/Distro/5/Anaconda</command>
0fe2f1
    </cmdsynopsis>
0fe2f1
0fe2f1
    <cmdsynopsis>
47422e
        <command>centos-art render Identity/Images/Themes/Modern --filter="2/Distro/5/Anaconda"</command>
0fe2f1
    </cmdsynopsis>
0fe2f1
0fe2f1
    <para>
0fe2f1
        You can use whatever combination you like whenever it matches
0fe2f1
        a valid render-able directory inside the working copy. But it
0fe2f1
        seems to be an acceptable practice to use the
0fe2f1
        <replaceable>LOCATION</replaceable> argument to specify the
0fe2f1
        render-able directory path inside the 
47422e
        class="directory">Identity/Images/Themes</filename>
0fe2f1
        directory which images need to be rendered for and the
0fe2f1
        <option>--filter</option> option only when it is needed to
0fe2f1
        restrict rendition to a specific file inside the directory
0fe2f1
        provided as <replaceable>LOCATION</replaceable>.
0fe2f1
    </para>
0fe2f1
ed015e
    </refsection>
ed015e
a491c8
    <refsection id="scripts-bash-render-description-baseflow">
a491c8
    <title>Base-Rendition Flow</title>
a491c8
    <para>
a491c8
        ...
a491c8
    </para>
a491c8
    </refsection>
a491c8
a491c8
    <refsection id="scripts-bash-render-description-postflow">
a491c8
    <title>Post-Rendition Flow </title>
ed015e
    <para>
ed015e
        ...
ed015e
    </para>
ed015e
    </refsection>
ed015e
a491c8
    <refsection id="scripts-bash-render-description-lastflow">
a491c8
    <title>Last-Rendition Flow </title>
a491c8
    <para>
a491c8
        ...
a491c8
    </para>
a491c8
    </refsection>
0fe2f1
0fe2f1
    <refsection id="scripts-bash-render-description-conffiles">
0fe2f1
    <title>Configuration Files (<filename>render.conf</filename>)</title>
0fe2f1
    <para>
0fe2f1
        ...
0fe2f1
    </para>
0fe2f1
    </refsection>
a491c8
    </refsection>
a491c8
ed015e
    <refsection id="scripts-bash-render-usage">
ed015e
    <title>Usage</title>
ed015e
    <para>
ed015e
        ...
ed015e
    </para>
ed015e
    </refsection>
ed015e
ed015e
    <refsection id="scripts-bash-render-option">
ed015e
    <title>Options</title>
ed015e
ed015e
    <para>
ed015e
        The <command>centos-art prepare</command> command accepts
ed015e
        common options described in 
42321e
        linkend="scripts-bash-cliref-options" /> and the following
ed015e
        specific options:
0ace69
    </para>
ed015e
ed015e
    <variablelist>
0ace69
0ace69
    <varlistentry>
0ace69
    <term><option>--answer-yes</option></term>
0ace69
    <listitem>
0ace69
    <para>
0ace69
       Assume <emphasis>yes</emphasis> to all confirmation requests.
0ace69
    </para>
0ace69
    </listitem>
0ace69
    </varlistentry>
0ace69
0ace69
    <varlistentry>
a491c8
    <term><option>--filter="<replaceable>REGEX</replaceable>"</option></term>
0ace69
    <listitem>
0ace69
    <para>
0ace69
        This option reduces the list of files to process inside
a491c8
        <replaceable>LOCATION</replaceable> using
a491c8
        <replaceable>REGEX</replaceable> as <replaceable>REGUEX</replaceable>
a491c8
        using <replaceable>REGEX</replaceable> as files you want to render.
a491c8
        The deeper you go into the directory structure the more
a491c8
        specific you'll be about the files you want to render.  When
a491c8
        you cannot go deeper into the directory structure through
a491c8
        <replaceable>LOCATION</replaceable> specification, use this
a491c8
        option to reduce the list of files therein.
0ace69
    </para>
0ace69
    </listitem>
0ace69
    </varlistentry>
0ace69
0ace69
    <varlistentry>
3b9515
    <term><option>--synchronize</option></term>
0ace69
    <listitem>
0ace69
    <para>
464f9a
        Synchronizes available changes between the working copy and
464f9a
        the central repository.
0ace69
    </para>
0ace69
    </listitem>
0ace69
    </varlistentry>
0ace69
0ace69
    <varlistentry>
a491c8
    <term><option>--releasever="<replaceable>RELEASE</replaceable>"</option></term>
0ace69
    <listitem>
0ace69
    <para>
0ace69
        This option expands the =\RELEASE=,
0ace69
        =\MAJOR_RELEASE=, and
0ace69
        =\MINOR_RELEASE= translation makers based on
a491c8
        <replaceable>NUMBER</replaceable> value.  Notice that
a491c8
        translation markers here were escaped using a backslash
a491c8
        (\) in order to prevent their expansion. Use this
a491c8
        option when you need to produce release-specific contents, but
a491c8
        no release information can be retrived from the directory path
a491c8
        you are currently rendering.
0ace69
    </para>
0ace69
    </listitem>
0ace69
    </varlistentry>
0ace69
0ace69
    <varlistentry>
a491c8
    <term><option>--basearch="<replaceable>BASEARCH</replaceable>"</option></term>
0ace69
    <listitem>
0ace69
    <para>
0ace69
        This option expands the =\ARCHITECTURE=,
a491c8
        translation makers based on <replaceable>ARHC</replaceable> value.
0ace69
        Notice that translation markers here were escaped using a
0ace69
        backslash (\) in order to prevent their
0ace69
        expansion. Use this option when you need to produce
0ace69
        architecture-sepecific contents but no architecture
0ace69
        information can be retrived from the directory path you are
0ace69
        currently rendering.
0ace69
    </para>
0ace69
    </listitem>
0ace69
    </varlistentry>
0ace69
0ace69
    <varlistentry>
a491c8
    <term><option>--theme-model="<replaceable>MODELNAME</replaceable>"</option></term>
0ace69
    <listitem>
0ace69
    <para>
0ace69
        This option specifies the name of theme model you want to use
0ace69
        when producing theme artistic motifs. By default, if this
0ace69
        option is not provided, the <literal>Default</literal> theme
0ace69
        model is used as reference to produce theme artistic motifs.
a491c8
        To know what values can be passed as
a491c8
        <replaceable>MODELNAME</replaceable>, run the following
a491c8
        command:
0ace69
    </para>
a491c8
a491c8
    <cmdsynopsis>
47422e
        <command>ls ${TCAR_WORKDIR}/Identity/Models/Themes</command>
a491c8
    </cmdsynopsis>
a491c8
0ace69
    </listitem>
0ace69
    </varlistentry>
0ace69
0ace69
    <varlistentry>
a491c8
    <term><option>--post-rendition="<replaceable>COMMAND</replaceable>"</option></term>
0ace69
    <listitem>
0ace69
    <para>
0ace69
        This option lets you apply a command as post-rendition action.
a491c8
        In this case, the <replaceable>COMMAND</replaceable>
a491c8
        represents the command-line you want to execute in order to
a491c8
        perform in-place modifications to base-rendition output.
0ace69
    </para>
0ace69
    </listitem>
0ace69
    </varlistentry>
0ace69
0ace69
    <varlistentry>
a491c8
    <term><option>--last-rendition="<replaceable>COMMAND</replaceable>"</option></term>
0ace69
    <listitem>
0ace69
    <para>
0ace69
        This option lets you apply a command as last-rendition action.
a491c8
        In this case, the <replaceable>COMMAND</replaceable> argument
0ace69
        represents the command string you want to execute in order to
0ace69
        perform in-place modifications to base-rendition,
0ace69
        post-rendition and directory-specific rendition outputs. 
0ace69
    </para>
0ace69
    </listitem>
0ace69
    </varlistentry>
0ace69
    </variablelist>
ed015e
    </refsection>
6104cf
a491c8
    <refsection id="scripts-bash-render-examples">
a491c8
    <title>Examples</title>
a491c8
    <para>
a491c8
        ...
a491c8
    </para>
a491c8
    </refsection>
a491c8
a491c8
    <refsection id="scripts-bash-render-bugs">
a491c8
    <title>Bugs</title>
a491c8
    <para>
a491c8
        To report bugs related to this function, please create a new
a491c8
        ticket 
a491c8
        url="https://projects.centos.org/trac/artwork/newticket?summary=Error%20Standardizing%20Rendition%20Tasks&component=Scripts">here</ulink>
a491c8
        refering the specific problems you found in it. For example,
a491c8
        it would be useful if you copy and paste any error output from
a491c8
        <command>centos-art.sh</command> script.
a491c8
    </para>
a491c8
    </refsection>
a491c8
ed015e
    <refsection id="scripts-bash-render-authors">
6104cf
    <title>Authors</title>
6104cf
    <para>
a491c8
        The following people have worked in this functionality:
6104cf
    </para>
6104cf
    <itemizedlist>
6104cf
    <listitem>
6104cf
    <para>
515dd1
        Alain Reguera Delgado <<ulink url="mailto:alain.reguera@gmail.com">alain.reguera@gmail.com</ulink>>, =COPYRIGHT_YEAR_LIST=
6104cf
    </para>
6104cf
    </listitem>
6104cf
    </itemizedlist>
ed015e
    </refsection>
6104cf
ed015e
    <refsection id="scripts-bash-render-licence">
6104cf
    <title>License</title>
515dd1
6104cf
    <para>
515dd1
        Copyright © =COPYRIGHT_YEAR_LIST= The CentOS Project
515dd1
    </para>
6104cf
 
515dd1
    <para>
515dd1
        This program is free software; you can redistribute it and/or
515dd1
        modify it under the terms of the GNU General Public License as
515dd1
        published by the Free Software Foundation; either version 2 of
515dd1
        the License, or (at your option) any later version.
515dd1
    </para>
6104cf
 
515dd1
    <para>
515dd1
        This program is distributed in the hope that it will be
515dd1
        useful, but WITHOUT ANY WARRANTY; without even the implied
515dd1
        warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
515dd1
        PURPOSE.  See the GNU General Public License for more details.
515dd1
    </para>
6104cf
 
515dd1
    <para>
515dd1
        You should have received a copy of the GNU General Public
515dd1
        License along with this program; if not, write to the Free
515dd1
        Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139,
515dd1
        USA.
6104cf
    </para>
ed015e
    </refsection>
0ace69
ed015e
</refentry>