#!/usr/bin/perl -w
#
# Luis Mondesi <lemsx1@gmail.com> 
# a simple script to generate a man page for splashy-theme.xml
#
# use: pod2man splashy-theme.xml.pod
#
use Pod::Text;
my $parser = Pod::Text->new (sentence => 0, width => 78);
$parser->parse_from_file($0,\*STDOUT);
exit 0;

=head1 NAME

B<Splashy> - a user-mode, POSIX and LSB compliant, boot splashing
system for UNIX.

=head1 SYNOPSIS

B</etc/splashy/themes/*/theme.xml> - Splashy theme configuration file

=head1 DESCRIPTION

B</etc/splashy/themes/*/theme.xml> describes the theme's behaviour

The theme on which the file will have effect is the one which is contained in the same directory as this theme.xml file

This configuration file is an XML file where all values are enclosed in tags

A tag is anything enclosed between B<< < >> and B<< > >>. An opening tag has the form C<< <tag> >> while a closing tag has its name preceded with a backslash (B<\>) character as in C<< <\tag> >>

Tags can be considered as folders. Each tag either contains tags or contains a value

The value of the final tag affects in the field defined by its parents tags

The following tag folders are supported:

=over 8

=item I<< <splashy> >>

This is the main container. All tags must be contained inside this tag

The following values are allowed in it: I<< <theme> >>, I<< <progressbar> >>, I<< <background> >>, I<< <textbox> >>, I<< <autoverboseonerror> >>, I<< <progressbaronboot> >>, I<< <progressbaronshutdown> >>

=item I<< <theme> >>

Defines the theme's metadata information

The following values are allowed in it: I<< <name> >>, I<< <version> >>, I<< <description> >>, I<< <urls> >>, I<< <author> >>

=item I<< <progressbar> >>

Defines how the theme's progress bar should look like and behave

The following values are allowed in it: I<< <x> >>, I<< <y> >>, I<< <width> >>, I<< <height> >>, I<< <red> >>, I<< <green> >>, I<< <blue> >>, I<< <alpha> >>, I<< <border> >>

=item I<< <border> >>

Defines how the border should be displayed

The following values are allowed in it: I<< <show> >>, I<< <red> >>, I<< <green> >>, I<< <blue> >>, I<< <alpha> >>

=item I<< <background> >>

Defines how the background image in the theme should look

The following values are allowed in it: I<< <boot> >>, I<< <shutdown> >>, I<< <errorimg> >>, I<< <width> >>, I<< <height> >>

=item I<< <textbox> >>

Defines how the textbox should be displayed

The following values are allowed in it: I<< <enable> >>, I<< <x> >>, I<< <y> >>, I<< <width> >>, I<< <height> >>, I<< <background> >>, I<< <border> >>, I<< <text> >>

=item I<< <text> >>

Describes how the text should look like

The following values are allowed in it: I<< <font> >>, I<< <red> >>, I<< <green> >>, I<< <blue> >>, I<< <alpha> >>

=item I<< <font> >>

Describes the font to use for text

The following values are allowed in it: I<< <file> >>, I<< <height> >>

=back

The following values are supported:

=over 8

=item I<< <name> >>

Name of the theme

=item I<< <version> >>

Version of the theme

=item I<< <description> >>

Brief description about the theme

=item I<< <urls> >>

Official URL(s) of the theme or the author

=item I<< <author> >>

Name or nickname of the theme's author

=item I<< <x> >>

Vertical starting possition of the element in pixels counting from the top of the display

=item I<< <y> >>

Horitzontal starting possition of the element in pixels counting from the left of the display

=item I<< <width> >>

Width of the element in pixels

=item I<< <height> >>

Height of the element in pixels

=item I<< <red> >>

Amount of red to colour the element. The value must be in the range 0-255

=item I<< <green> >>

Amount of green to colour the element. The value must be in the range 0-255

=item I<< <blue> >>

Amount of blue to colour the element. The value must be in the range 0-255

=item I<< <alpha> >>

Level of transparency the element. The value must be in the range 0-255

=item I<< <show> >>

Display or hide the element. Possible values are 'yes' and 'no'

=item I<< <boot> >>

Complete path to a file containing the image to show as background on boot

=item I<< <shutdown> >>

Complete path to a file containing the image to show as background on shutdown

=item I<< <errorimg> >>

Complete path to a file containing the image to show as backgraund when an error occurs

=item I<< <enable> >>

Display or hide the element. Possible values are 'yes' and 'no'

=item I<< <file> >>

Complete path to a file containing the data refered by the parent tag

=item I<< <autoverboseonerror> >>

Switch to console if error happens. Possible values are 'yes' and 'no'

=item I<< <progressbaronboot> >>

Display a progress bar while the system boots. Possible values are 'yes' and 'no'

=item I<< <progressbaronshutdown> >>

Display a progress bar while the system shuts down. Possible values are 'yes' and 'no'

=back

=head1 EXAMPLES

The following is a complete and valid splashy theme configuration file:

 <splashy>
    <theme>
        <!-- theme name is case sensitive. use directory name -->
        <name>default</name>
        <version>1.0</version>
        <description>Default splashy theme</description>
        <urls>http://splashy.alioth.debian.org/themes</urls>
        <author>Splashy Team</author>
    </theme>
    <progressbar>
        <!-- here are tags to set the bar... x coordinate,
        y coordinate, width and height are for the progress bar.
        Remember that x, y, width and height are expressed in percentage -->
        <x>10</x>
        <y>90</y>
        <width>80</width>
        <height>5</height>
        <!-- here you can set the color of the progressbar...
        set the amount of red, green, blue and alpha channel. 
        Remember that the max value is 255 and the minumun value is 0-->
        <red>255</red>
        <green>156</green>
        <blue>0</blue>
        <alpha>255</alpha>
        <!-- whether or not you want a border around the progressbar. default: no -->
        <border>
            <show>yes</show>
            <red>0</red>
            <green>0</green>
            <blue>0</blue>
            <alpha>255</alpha>
        </border>
    </progressbar>
    <!-- conventional path: /etc/splashy/themes + theme-name -->
    <background>
        <boot>background.jpg</boot>
        <shutdown>background.jpg</shutdown>
        <errorimg>error.jpg</errorimg>
        <!-- resolution of the images. this value affects where 
        the progressbar will be drawn. If VALUE <= 0, then percentages
        of the screen width and hight will be assumed -->
        <width>0</width>
        <height>0</height>
    </background>
    <textbox>
        <!-- whether you want the textbox always
        shown or no. If no, it will be shown only on error, 
        see autoverboseonerror -->
        <enable>yes</enable>
        <!-- here are tags to set the text area... x coordinate,
        y coordinate, width and height are for the text area.
        Remember that x, y, width and height are expressed in percentage
        or pixel units -->
        <x>20</x>
        <y>50</y>
        <width>60</width>
        <height>40</height>
        <!-- here you can set the color of the text area...
        set the amount of red, green, blue and alpha channel. 
        Remember that the max value is 255 and the minumun value is 0-->
        <background>
            <red>0</red>
            <green>0</green>
            <blue>0</blue>
            <alpha>127</alpha>
        </background>
        <!-- whether or not you want a border around the progressbar. default: no -->
        <border>
            <show>yes</show>
            <red>0</red>
            <green>0</green>
            <blue>0</blue>
            <alpha>255</alpha>
        </border>
        <text>
            <!-- font file to use, path relative to theme -->
            <font>
                <file>FreeMono.ttf</file>
                <height>10</height>
            </font>
            <!-- here you can set the color of the text/font...
            set the amount of red, green, blue and alpha channel. 
            Remember that the max value is 255 and the minumun value is 0-->
            <red>128</red>
            <green>128</green>
            <blue>32</blue>
            <alpha>255</alpha>
	</text>
    </textbox>
    <autoverboseonerror>yes</autoverboseonerror>
    <progressbaronboot>yes</progressbaronboot>
    <progressbaronshutdown>yes</progressbaronshutdown>
 </splashy>

=head1 NOTES

Values are refered by their tag name prefixed with all of its parent tag's names. For example: C</splashy/theme/name>

All values must be defined. Otherwise unpredictable things may happen

=head1 FILES

=over 8

=item I</etc/splashy/themes/*/theme.xml>

Main theme configuration. Defines the theme's layout

=item I</etc/splashy/themes/>

Location where splashy themes are stored

=back

=head1 SEE ALSO

B<splashy>(1), B<splashy_config>(1), B<splashy_config>(1), B<splashy-config.xml>(5)

=head1 AUTHORS
		
Jacobo Vilella <jacobo221@gmail.com>

=cut
