added tuts
Tobias Leich [Sun, 15 Nov 2009 14:34:30 +0000 (15:34 +0100)]
.htaccess [new file with mode: 0644]
cgi-bin/sdl.cgi [changed mode: 0755->0644]
index.php [new file with mode: 0644]
pages/SDL-Tutorial-Animation.html-inc [new file with mode: 0644]
pages/SDL-Tutorial-Images.html-inc [new file with mode: 0644]
pages/SDL-Tutorial-LunarLander.html-inc [new file with mode: 0644]
pages/SDL-Tutorial-Pong.html-inc [new file with mode: 0644]
pages/SDL-Tutorial-Tetris.html-inc [new file with mode: 0644]
pages/documentation.html-inc
tools/PM-Pod2html-snippet.pl [new file with mode: 0644]
tools/RSS2html-snippet.pl [new file with mode: 0644]

diff --git a/.htaccess b/.htaccess
new file mode 100644 (file)
index 0000000..1915102
--- /dev/null
+++ b/.htaccess
@@ -0,0 +1,4 @@
+RewriteEngine on
+
+RewriteRule ^(.*)\.html$ index.php?$1 [L]
+RewriteRule ^assets/(.*)$ htdocs/assets/$1 [L]
old mode 100755 (executable)
new mode 100644 (file)
diff --git a/index.php b/index.php
new file mode 100644 (file)
index 0000000..6b7ba98
--- /dev/null
+++ b/index.php
@@ -0,0 +1,16 @@
+<?php
+
+$layout = file_get_contents('layout.html');
+
+$_SERVER{'QUERY_STRING'} = preg_replace('/\.\.\//', '', $_SERVER{'QUERY_STRING'});
+
+if(file_exists("pages/{$_SERVER{'QUERY_STRING'}}.html-inc"))
+{
+       echo strtr($layout, array('<div id="main" />' => '<div id="main">' . file_get_contents("pages/{$_SERVER{'QUERY_STRING'}}.html-inc") . '</div>'));
+}
+else
+{
+       echo strtr($layout, array('<div id="main" />' => '<div id="main">' . file_get_contents("pages/index.html-inc") . '</div>'));
+}
+
+?>
\ No newline at end of file
diff --git a/pages/SDL-Tutorial-Animation.html-inc b/pages/SDL-Tutorial-Animation.html-inc
new file mode 100644 (file)
index 0000000..51fcdcf
--- /dev/null
@@ -0,0 +1,180 @@
+<div class="pod">
+<!-- INDEX START -->
+<h3 id="TOP">Index</h3>
+
+<ul><li><a href="#NAME">NAME</a></li>
+<li><a href="#SYNOPSIS">SYNOPSIS</a></li>
+<li><a href="#ANIMATING_A_RECTANGLE">ANIMATING A RECTANGLE</a>
+<ul><li><a href="#Redrawing_the_Screen">Redrawing the Screen</a></li>
+<li><a href="#Undrawing_the_Updated_Rectangle">Undrawing the Updated Rectangle</a></li>
+</ul>
+</li>
+<li><a href="#SEE_ALSO">SEE ALSO</a></li>
+<li><a href="#AUTHOR">AUTHOR</a></li>
+<li><a href="#BUGS">BUGS</a></li>
+<li><a href="#COPYRIGHT">COPYRIGHT</a>
+</li>
+</ul><hr />
+<!-- INDEX END -->
+
+<h1 id="NAME">NAME</h1><p><a href="#TOP" class="toplink">Top</a></p>
+<div id="NAME_CONTENT">
+<p>SDL::Tutorial::Animation</p>
+
+</div>
+<h1 id="SYNOPSIS">SYNOPSIS</h1><p><a href="#TOP" class="toplink">Top</a></p>
+<div id="SYNOPSIS_CONTENT">
+<pre>  # to read this tutorial
+       $ perldoc SDL::Tutorial::Animation
+
+       # to create a demo animation program based on this tutorial
+       $ perl -MSDL::Tutorial::Animation=sdl_anim.pl -e 1
+
+</pre>
+
+</div>
+<h1 id="ANIMATING_A_RECTANGLE">ANIMATING A RECTANGLE</h1><p><a href="#TOP" class="toplink">Top</a></p>
+<div id="ANIMATING_A_RECTANGLE_CONTENT">
+<p>Now that you can display a rectangle on the screen, the next step is to animate
+that rectangle.  As with movies, there's no actual motion.  Computer animations are just very very fast slideshows.  The hard work is creating nearly identical images in every slide (or frame, in graphics terms).</p>
+<p>Okay, it's not that difficult.</p>
+<p>There is one small difficulty to address, however.  Once you blit one surface
+onto another, the destination is changed permanently.  There's no concept of
+layers here unless you write it yourself.  If you fail to take this into
+account (and just about everyone does at first), you'll end up with blurry
+graphics moving around on the screen.</p>
+<p>There are two approaches to solve this problem, redrawing the screen on every
+frame and saving and restoring the background for every object drawn.</p>
+
+</div>
+<h2 id="Redrawing_the_Screen">Redrawing the Screen</h2>
+<div id="Redrawing_the_Screen_CONTENT">
+<p>Since you have to draw the screen in the right order once to start with it's
+pretty easy to make this into a loop and redraw things in the right order for
+every frame.  Given a <cite>SDL::App</cite> object <code>$app</code>, a <cite>SDL::Rect</cite> <code>$rect</code>, and
+a <cite>SDL::Color</cite> <code>$color</code>, you only have to create a new SDL::Rect <code>$bg</code>,
+representing the whole of the background surface and a new SDL::Color
+<code>$bg_color</code>, representing the background color.  You can write a
+<code>draw_frame()</code> function as follows:</p>
+<p>&nbsp;</p>
+<pre>  sub draw_frame
+       {
+               my ($app, %args) = @_;
+
+               $app-&gt;fill( $args{ bg }, $args{ bg_color } );
+               $app-&gt;fill( $args{rect}, $args{rect_color} );
+               $app-&gt;update( $args{bg} );
+       }
+
+</pre>
+<p>&nbsp;</p>
+<p>Since you can change the <code>x</code> and <code>y</code> coordinates of a rect with the <code>x()</code>
+and <code>y()</code> methods, you can move a rectangle across the screen with a loop like
+this:</p>
+<p>&nbsp;</p>
+<pre>  for my $x (0 .. 640)
+       {
+               $rect-&gt;x( $x );
+               draw_frame( $app,
+                       bg   =&gt; $bg,   bg_color   =&gt; $bg_color,
+                       rect =&gt; $rect, rect_color =&gt; $color,
+               );
+       }
+
+</pre>
+<p>&nbsp;</p>
+<p>If <code>$rect</code>'s starting y position is 190 and its height and width are 100, the
+rectangle (er, square) will move across the middle of the screen.</p>
+<p>Provided you can keep track of the proper order in which to redraw rectangles
+and provided you don't need the optimal speed necessary (since blitting every
+object takes more work than just blitting the portions you need), this works
+quite well.</p>
+
+</div>
+<h2 id="Undrawing_the_Updated_Rectangle">Undrawing the Updated Rectangle</h2>
+<div id="Undrawing_the_Updated_Rectangle_CONT">
+<p>If you need more speed or want to make a different complexity tradeoff, you can
+take a snapshot of the destination rectangle <i>before</i> you blit onto it.  That
+way, when you need to redraw, you can blit the old snapshot back before
+blitting to the new position.</p>
+<p><strong>Note:</strong>  I have no idea how this will work in the face of alpha blending,
+which, admittedly, I haven't even mentioned yet.  If you don't know what this
+means, forget it.  If you do know what this means and know why I'm waving my
+hands here, feel free to explain what should and what does happen and why.  :)</p>
+<p>With this technique, the frame-drawing subroutine has to be a little more
+complicated.  Instead of the background rect, it needs a rect for the previous
+position.  It also needs to do two updates (or must perform some scary math to
+figure out the rectangle of the correct size to <code>update()</code>.  No thanks!).</p>
+<p>&nbsp;</p>
+<pre>  sub undraw_redraw_rect
+       {
+               my ($app, %args) = @_;
+
+               $app-&gt;fill(   $args{old_rect}, $args{bg_color}   );
+               $app-&gt;fill(   $args{rect],     $args{rect_color} );
+               $app-&gt;update( $args{old_rect}, $args{rect}       );
+       }
+
+</pre>
+<p>&nbsp;</p>
+<p>We'll need to create a new SDL::Rect, <code>$old_rect</code>, that is a duplicate of
+<code>$rect</code>, at the same position at first.  You should already know how to do
+this.</p>
+<p>As before, the loop to call <code>undraw_redraw_rect()</code> would look something like:</p>
+<p>&nbsp;</p>
+<pre>  for my $x (0 .. 640)
+       {
+               $rect-&gt;x( $x );
+
+               undraw_redraw_rect( $app,
+                       rect       =&gt; $rect,  old_rect =&gt; $old_rect,
+                       rect_color =&gt; $color, bg_color =&gt; $bgcolor,
+               );
+
+               $old_rect-&gt;x( $x );
+       }
+
+</pre>
+<p>&nbsp;</p>
+<p>If you run this code, you'll probably notice that it's tremendously faster than
+the previous version.  It may be too fast, where the alternate technique was
+just fast enough.  There are a couple of good ways to set a fixed animation
+speed regardless of the speed of the processor and graphics hardware (provided
+they're good enough, which is increasingly often the case), and we'll get to
+them soon.</p>
+
+</div>
+<h1 id="SEE_ALSO">SEE ALSO</h1><p><a href="#TOP" class="toplink">Top</a></p>
+<div id="SEE_ALSO_CONTENT">
+<dl>
+       <dt><cite>SDL::Tutorial::Drawing</cite></dt>
+       <dd>
+               <p>basic drawing with SDL Perl</p>
+       </dd>
+       <dt><cite>SDL::Tutorial::Images</cite></dt>
+       <dd>
+               <p>animating images</p>
+       </dd>
+</dl>
+
+</div>
+<h1 id="AUTHOR">AUTHOR</h1><p><a href="#TOP" class="toplink">Top</a></p>
+<div id="AUTHOR_CONTENT">
+<p>chromatic, &lt;chromatic@wgz.org&gt;</p>
+<p>Written for and maintained by the Perl SDL project, <a href="http://sdl.perl.org/">http://sdl.perl.org/</a>.</p>
+
+</div>
+<h1 id="BUGS">BUGS</h1><p><a href="#TOP" class="toplink">Top</a></p>
+<div id="BUGS_CONTENT">
+<p>No known bugs.</p>
+
+</div>
+<h1 id="COPYRIGHT">COPYRIGHT</h1><p><a href="#TOP" class="toplink">Top</a></p>
+<div id="COPYRIGHT_CONTENT">
+<p>Copyright (c) 2003 - 2004, chromatic.  All rights reserved.  This module is
+distributed under the same terms as Perl itself, in the hope that it is useful
+but certainly under no guarantee.
+</p>
+
+</div>
+</div>
\ No newline at end of file
diff --git a/pages/SDL-Tutorial-Images.html-inc b/pages/SDL-Tutorial-Images.html-inc
new file mode 100644 (file)
index 0000000..6c9aa01
--- /dev/null
@@ -0,0 +1,224 @@
+<div class="pod">
+<!-- INDEX START -->
+<h3 id="TOP">Index</h3>
+
+<ul><li><a href="#NAME">NAME</a></li>
+<li><a href="#SYNOPSIS">SYNOPSIS</a></li>
+<li><a href="#ANIMATING_IMAGES">ANIMATING IMAGES</a>
+<ul><li><a href="#Loading_Images">Loading Images</a></li>
+<li><a href="#Displaying_Images">Displaying Images</a></li>
+<li><a href="#Multi_Image_Animation">Multi-Image Animation</a></li>
+</ul>
+</li>
+<li><a href="#SEE_ALSO">SEE ALSO</a></li>
+<li><a href="#AUTHOR">AUTHOR</a></li>
+<li><a href="#BUGS">BUGS</a></li>
+<li><a href="#COPYRIGHT">COPYRIGHT</a>
+</li>
+</ul><hr />
+<!-- INDEX END -->
+
+<h1 id="NAME">NAME</h1><p><a href="#TOP" class="toplink">Top</a></p>
+<div id="NAME_CONTENT">
+<p>SDL::Tutorial::Images</p>
+
+</div>
+<h1 id="SYNOPSIS">SYNOPSIS</h1><p><a href="#TOP" class="toplink">Top</a></p>
+<div id="SYNOPSIS_CONTENT">
+<pre>  # to read this tutorial
+       $ perldoc SDL::Tutorial::Images
+
+       # to create a demo animation program based on this tutorial
+       $ perl -MSDL::Tutorial::Images=sdl_images.pl -e 1
+
+</pre>
+
+</div>
+<h1 id="ANIMATING_IMAGES">ANIMATING IMAGES</h1><p><a href="#TOP" class="toplink">Top</a></p>
+<div id="ANIMATING_IMAGES_CONTENT">
+<p>Since you're already familiar with the concepts behind animation, it's time to
+learn how to work with images.  As usual, the important point is that computer animation is just <i>simulating</i> motion by painting several slightly different frames to the screen every second.</p>
+<p>There are two ways to vary an image on screen.  One is to change its
+coordinates so it's at a slightly different position.  This is very easy to do;
+it's just like animating a rectangle.  The other way is to change the image
+itself so it's slightly different.  This is a little more difficult, as you'll
+need to draw the alternate image beforehand somehow.</p>
+
+</div>
+<h2 id="Loading_Images">Loading Images</h2>
+<div id="Loading_Images_CONTENT">
+<p>As usual, start with an <cite>SDL::App</cite> object representing the image window.  Then
+preload the image file.  This is easy; just pass the <code>name</code> parameter to the
+<cite>SDL::Surface</cite> constructor:</p>
+<p>&nbsp;</p>
+<pre>  use SDL::Surface;
+
+       my $frame = SDL::Surface-&gt;new( -name =&gt; 'frame1.png' );
+
+</pre>
+<p>&nbsp;</p>
+<p><strong>Note:</strong> you'll need to have compiled SDL Perl (and probably SDL) to support
+JPEG and PNG files for this to work.</p>
+<p>That's it; now you have an SDL::Surface object containing the image.  You can
+use the <code>height()</code>, <code>width()</code>, and <code>bpp()</code> methods to retrieve its height,
+width, and bits per pixel, if you need them.</p>
+
+</div>
+<h2 id="Displaying_Images">Displaying Images</h2>
+<div id="Displaying_Images_CONTENT">
+<p>Drawing an image onto the screen requires blitting it from one surface to
+another.  (Remember, &quot;blitting&quot; means copying bits in memory.)  The <code>blit()</code>
+method of SDL::Surface objects comes in handy.  Its arguments are a little odd,
+though.  Assuming <code>$app</code> is the SDL::App object, as usual:</p>
+<p>&nbsp;</p>
+<pre>  use SDL::Rect;
+
+       my $frame_rect = SDL::Rect-&gt;new(
+               -height =&gt; $frame-&gt;height(),
+               -width  =&gt; $frame-&gt;width(),
+               -x      =&gt; 0,
+               -y      =&gt; 0,
+       );
+
+       my $dest_rect  = SDL::Rect-&gt;new(
+               -height =&gt; $frame-&gt;height(),
+               -width  =&gt; $frame-&gt;width(),
+               -x      =&gt; 0,
+               -y      =&gt; 0,
+       );
+
+       $frame-&gt;blit( $frame_rect, $app, $dest_rect );
+       $app-&gt;update( $dest_rect );
+
+</pre>
+<p>&nbsp;</p>
+<p>Here we have two <cite>SDL::Rect</cite> objects which represent rectangular regions of a
+Surface.  <code>$frame_rect</code> represents the entire area of <code>$frame</code>, while
+<code>$dest_rect</code> represents the area of the main window in which to blit the
+frame.  This may be clearer with more descriptive variable names:</p>
+<p>&nbsp;</p>
+<pre>  $source_surface-&gt;blit(
+               $area_of_source_to_blit,
+               $destination_surface,
+               $destination_area
+       );
+
+</pre>
+<p>&nbsp;</p>
+<p>As usual, call <code>update()</code> on <code>$app</code> to see the change.</p>
+<p>Requiring the source and destination Rect objects may seem tedious in this
+simple example, but it's highly useful for copying only part of surface to part
+of another.  For example, animating this image is a matter of changing the <code>x</code>
+and <code>y</code> coordinates of <code>$dest_rect</code>:</p>
+<p>&nbsp;</p>
+<pre>  for my $x ( 1 .. 100 )
+       {
+               $dest_rect-&gt;x( $x );
+               $frame-&gt;blit( $frame_rect, $app, $dest_rect );
+               $app-&gt;update( $dest_rect );
+       }
+
+</pre>
+<p>&nbsp;</p>
+<p>Of course, you'll have to redraw all or part of the screen to avoid artifacts,
+as discussed in the previous tutorial.</p>
+
+</div>
+<h2 id="Multi_Image_Animation">Multi-Image Animation</h2>
+<div id="Multi_Image_Animation_CONTENT">
+<p>That covers moving a single image around the screen.  What if you want
+something more?  For example, what if you want to animate a stick figure
+walking?</p>
+<p>You'll need several frames, just as in a flip-book.  Each frame should be slightly different than the one before it.  It's probably handy to encapsulate all of this in a <code>Walker</code> class:</p>
+<p>&nbsp;</p>
+<pre>  package Walker;
+
+       use SDL::Surface;
+
+       sub new
+       {
+               my ($class, @images) = @_;
+               my $self = [ map { SDL::Surface-&gt;new( -name =&gt; $_ ) } @images ];
+
+               bless $self, $class;
+       }
+
+       sub next_frame
+       {
+               my $self  = shift;
+               my $frame = shift @$self;
+
+               push @$self, $frame;
+               return $frame;
+       }
+
+</pre>
+<p>&nbsp;</p>
+<p>To use this class, instantiate an object:</p>
+<p>&nbsp;</p>
+<pre>  my $walker = Walker-&gt;new( 'frame1.png', 'frame2.png', 'frame3.png' );
+
+</pre>
+<p>&nbsp;</p>
+<p>Then call <code>next_frame()</code> within the loop:</p>
+<p>&nbsp;</p>
+<pre>  for my $x ( 1 .. 100 )
+       {
+               my $frame = $walker-&gt;next_frame();
+
+               $dest_rect-&gt;x( $x );
+               $frame-&gt;blit( $frame_rect, $app, $dest_rect );
+               $app-&gt;update( $dest_rect );
+       }
+
+</pre>
+<p>&nbsp;</p>
+<p>Again, the rest of the frame drawing is missing from this example so as not to
+distract from this technique.  You'll probably want to abstract the undrawing
+and redrawing into a separate subroutine so you don't have to worry about it
+every time.</p>
+<p>It'd be easy to make <code>next_frame()</code> much smarter, selecting an image
+appropriate to the direction of travel, using a bored animation when the
+character is no longer moving, or adding other characteristics to the
+character.  As you can see, the hard part of this technique is generating the
+images beforehand.  That can add up to a tremendous amount of art and that's
+one reason for the popularity of 3D models... but that's another tutorial much
+further down the road.</p>
+<p>More importantly, it's time to discuss how to make these animations run more
+smoothly.  More on that next time.</p>
+
+</div>
+<h1 id="SEE_ALSO">SEE ALSO</h1><p><a href="#TOP" class="toplink">Top</a></p>
+<div id="SEE_ALSO_CONTENT">
+<dl>
+       <dt><cite>SDL::Tutorial</cite></dt>
+       <dd>
+               <p>basic SDL tutorial</p>
+       </dd>
+       <dt><cite>SDL::Tutorial::Animation</cite></dt>
+       <dd>
+               <p>non-image animation</p>
+       </dd>
+</dl>
+
+</div>
+<h1 id="AUTHOR">AUTHOR</h1><p><a href="#TOP" class="toplink">Top</a></p>
+<div id="AUTHOR_CONTENT">
+<p>chromatic, &lt;chromatic@wgz.org&gt;</p>
+<p>Written for and maintained by the Perl SDL project, <a href="http://sdl.perl.org/">http://sdl.perl.org/</a>.</p>
+
+</div>
+<h1 id="BUGS">BUGS</h1><p><a href="#TOP" class="toplink">Top</a></p>
+<div id="BUGS_CONTENT">
+<p>No known bugs.</p>
+
+</div>
+<h1 id="COPYRIGHT">COPYRIGHT</h1><p><a href="#TOP" class="toplink">Top</a></p>
+<div id="COPYRIGHT_CONTENT">
+<p>Copyright (c) 2004, chromatic.  All rights reserved.  This module is
+distributed under the same terms as Perl itself, in the hope that it is useful
+but certainly under no guarantee.
+</p>
+
+</div>
+</div>
\ No newline at end of file
diff --git a/pages/SDL-Tutorial-LunarLander.html-inc b/pages/SDL-Tutorial-LunarLander.html-inc
new file mode 100644 (file)
index 0000000..2efac82
--- /dev/null
@@ -0,0 +1,302 @@
+<div class="pod">
+<!-- INDEX START -->
+<h3 id="TOP">Index</h3>
+
+<ul><li><a href="#NAME">NAME</a></li>
+<li><a href="#INTRODUCTION">INTRODUCTION</a>
+<ul>
+<li>
+<ul><li><a href="#CREATING_A_DEMO">CREATING A DEMO</a></li>
+</ul>
+</li>
+<li><a href="#FIRST_VERSION">FIRST VERSION</a></li>
+<li><a href="#CONTROLLING_THE_SHIP">CONTROLLING THE SHIP</a></li>
+<li><a href="#HOW_ABOUT_THE_GRAPHICS">HOW ABOUT THE GRAPHICS?</a>
+<ul><li><a href="#THE_GRAPHICS">THE GRAPHICS</a></li>
+</ul>
+</li>
+<li><a href="#USING_SDL">USING SDL</a></li>
+</ul>
+</li>
+<li><a href="#COPYRIGHT_amp_LICENSE">COPYRIGHT &amp; LICENSE</a>
+</li>
+</ul><hr />
+<!-- INDEX END -->
+
+<h1 id="NAME">NAME</h1><p><a href="#TOP" class="toplink">Top</a></p>
+<div id="NAME_CONTENT">
+<p>Lunar Lander - a small tutorial on Perl SDL</p>
+
+</div>
+<h1 id="INTRODUCTION">INTRODUCTION</h1><p><a href="#TOP" class="toplink">Top</a></p>
+<div id="INTRODUCTION_CONTENT">
+<p>This is a quick introduction to Games, Perl, and  SDL (Simple 
+DirectMedia Layer, a cross-platform multimedia programming 
+library). We'll write a small game -- Lunar Lander -- in 100 
+lines of code, or less.</p>
+
+</div>
+<h3 id="CREATING_A_DEMO">CREATING A DEMO</h3>
+<div id="CREATING_A_DEMO_CONTENT">
+<p>You can see the final version of the demo code by doing:</p>
+<p>&nbsp;</p>
+<pre>   perl -MSDL::Tutorial::LunarLander=lander.pl -e1
+
+</pre>
+<p>&nbsp;</p>
+<p>this will create all three files used in the tutorial:</p>
+
+
+
+
+
+</div>
+<h2 id="FIRST_VERSION">FIRST VERSION</h2>
+<div id="FIRST_VERSION_CONTENT">
+<p>We'll start with a text version of the game.</p>
+<p>&quot;What?&quot;, you may ask. &quot;I thought it was a SDL tutorial&quot;.</p>
+<p>Yes, it is -- thank you for reminding me. But we'll leave the SDL part for
+later. We must build the game logic first!</p>
+<p>One of the traps of game programming is focusing too much on the interface.
+If we start with a simpler simulation, we can worry with the presentation
+later.</p>
+<p>So, here's the initial code:</p>
+<p>&nbsp;</p>
+<pre>    #!/usr/bin/perl
+
+    use strict;
+    use warnings;
+
+    my $height   = 1000; # m
+    my $velocity = 0;    # m/s
+    my $gravity  = 1;    # m/s^2
+
+    my $t = 0;
+
+    while ( $height &gt; 0 ) {
+        print &quot;at $t s height = $height m, velocity = $velocity m/s\n&quot;;
+
+        $height   = $height - $velocity;
+        $velocity = $velocity + $gravity;
+        $t        = $t + 1;
+    }
+
+    if ( $velocity &gt; 10 ) {
+        print &quot;CRASH!!!\n&quot;;
+    } else {
+        print &quot;You landed on the surface safely! :-D\n&quot;;
+    }
+
+</pre>
+<p>&nbsp;</p>
+<p>Run the code and you'll see something like this:</p>
+<p>&nbsp;</p>
+<pre>    at 0 s height = 1000 m, velocity = 0 m/s
+    at 1 s height = 1000 m, velocity = 1 m/s
+    at 2 s height = 999 m, velocity = 2 m/s
+    at 3 s height = 997 m, velocity = 3 m/s
+    at 4 s height = 994 m, velocity = 4 m/s
+    at 5 s height = 990 m, velocity = 5 m/s
+    ...
+    at 43 s height = 97 m, velocity = 43 m/s
+    at 44 s height = 54 m, velocity = 44 m/s
+    at 45 s height = 10 m, velocity = 45 m/s
+
+    CRASH!!!
+
+</pre>
+<p>&nbsp;</p>
+<p>&quot;What happened? How do I control the ship???&quot;</p>
+
+</div>
+<h2 id="CONTROLLING_THE_SHIP">CONTROLLING THE SHIP</h2>
+<div id="CONTROLLING_THE_SHIP_CONTENT">
+<p>The problem with our first spaceship is that it had no controls!</p>
+<p>So, let's fix this problem, making the spaceship scriptable. (We 
+could write some code to handle keyboard and joysticks now, but 
+an scriptable spaceship will be easier to start. Remember, focus
+on the game logic!)</p>
+<p>So, create add this simple script to the end of your file:</p>
+<p>&nbsp;</p>
+<pre>    __DATA__
+    at 41s, accelerate 10 m/s^2 up
+    at 43s, 10 m/s^2
+    at 45s, 10
+    at 47s, 10
+    at 49s, 10
+
+</pre>
+<p>&nbsp;</p>
+<p>The script is straightforward: it simply states a time when we
+will push the spaceship up with a given acceleration. It accepts
+free text: any two numbers you type will work.</p>
+<p>We can parse the script using this regular expression:</p>
+<p>&nbsp;</p>
+<pre>    my $script_re = qr/(\d+) \D+ (\d+)/x;
+
+</pre>
+<p>&nbsp;</p>
+<p>And we can build a hash of ( time =&gt; acceleration ) with:</p>
+<p>&nbsp;</p>
+<pre>    my %up = map { $_ =~ $script_re } &lt;DATA&gt;;
+
+</pre>
+<p>&nbsp;</p>
+<p>So the middle section of the program will become:</p>
+<p>&nbsp;</p>
+<pre>    my $script_re = qr/(\d+) \D+ (\d+)/x;
+    my %up = map { $_ =~ $script_re } &lt;DATA&gt;;
+
+    while ( $height &gt; 0 ) {
+        print &quot;at $t s height = $height m, velocity = $velocity m/s\n&quot;;
+
+        if ( $up{$t} ) {
+            my $a = $up{$t};
+            print &quot;(accellerating $a m/s^2)\n&quot;;
+            $velocity = $velocity - $a;
+        }
+
+        $height   = $height - $velocity;
+        $velocity = $velocity + $gravity;
+        $t        = $t + 1;
+    }
+
+</pre>
+<p>&nbsp;</p>
+<p>That's it!</p>
+<p>Try to run the program, and the ship should land safely:</p>
+<p>&nbsp;</p>
+<pre>    ./lunar.pl autopilot.txt 
+    at 0 s height = 1000 m, velocity = 0 m/s
+    at 1 s height = 1000 m, velocity = 1 m/s
+    at 2 s height = 999 m, velocity = 2 m/s
+    at 3 s height = 997 m, velocity = 3 m/s
+    at 4 s height = 994 m, velocity = 4 m/s
+    at 5 s height = 990 m, velocity = 5 m/s
+    ...
+    at 54 s height = 19 m, velocity = 4 m/s
+    at 55 s height = 15 m, velocity = 5 m/s
+    at 56 s height = 10 m, velocity = 6 m/s
+    at 57 s height = 4 m, velocity = 7 m/s
+
+    You landed on the surface safely! :-D
+
+</pre>
+<p>&nbsp;</p>
+<p>Cool, but...</p>
+
+</div>
+<h2 id="HOW_ABOUT_THE_GRAPHICS">HOW ABOUT THE GRAPHICS?</h2>
+<div id="HOW_ABOUT_THE_GRAPHICS_CONTENT">
+<p>Okay, okay... now that we have a working prototype, we can work on
+the graphics. But, first of all, we'll need...</p>
+
+</div>
+<h3 id="THE_GRAPHICS">THE GRAPHICS</h3>
+<div id="THE_GRAPHICS_CONTENT">
+<p>Yes, the graphics.</p>
+<p>We won't use anything fancy here, just two images: a large one, for
+the background, and a smaller one for the spaceship.</p>
+<p>Create the images using the Gimp, or use the images provided by
+this tutorial; Save these images in a subdirectory called &quot;images&quot;:
+(&quot;<code>images/background.jpg</code>&quot; and &quot;<code>images/ship.png</code>&quot;).</p>
+
+</div>
+<h2 id="USING_SDL">USING SDL</h2>
+<div id="USING_SDL_CONTENT">
+<p>First step: use the required libraries:</p>
+<p>&nbsp;</p>
+<pre>    use SDL; #needed to get all constants
+    use SDL::App;
+    use SDL::Surface;
+    use SDL::Rect;
+
+</pre>
+<p>&nbsp;</p>
+<p>Second step: initialize <code>SDL::App</code>:</p>
+<p>&nbsp;</p>
+<pre>    my $app = SDL::App-&gt;new(
+        -title  =&gt; &quot;Lunar Lander&quot;,
+        -width  =&gt; 800,
+        -height =&gt; 600,
+        -depth  =&gt; 32,
+    );
+
+</pre>
+<p>&nbsp;</p>
+<p>Third step: load the images and create the necessary &quot;rectangles&quot;:</p>
+<p>&nbsp;</p>
+<pre>    my $background = SDL::Surface-&gt;new( -name =&gt; 'images/background.jpg', );
+    my $ship       = SDL::Surface-&gt;new( -name =&gt; 'images/ship.png', );
+
+    my $background_rect = SDL::Rect-&gt;new(
+        -height =&gt; $background-&gt;height(),
+        -width  =&gt; $background-&gt;width(),
+    );
+
+    my $ship_rect = SDL::Rect-&gt;new(
+        -height =&gt; $ship-&gt;height(),
+        -width  =&gt; $ship-&gt;width(),
+    );
+
+</pre>
+<p>&nbsp;</p>
+<p>Fourth step: create a sub to draw the spaceship and background:</p>
+<p>&nbsp;</p>
+<pre>    sub draw {
+        my ( $x, $y ) = @_; # spaceship position
+
+        # fix $y for screen resolution
+        $y = 450 * ( 1000 - $y ) / 1000;
+
+        # background
+        $background-&gt;blit( $background_rect, $app, $background_rect );
+
+        # ship
+        my $ship_dest_rect = SDL::Rect-&gt;new(
+            -height =&gt; $ship-&gt;height(),
+            -width  =&gt; $ship-&gt;width(),
+            -x      =&gt; $x,
+            -y      =&gt; $y,
+        );
+
+        $ship-&gt;blit( $ship_rect, $app, $ship_dest_rect );
+
+        $app-&gt;update($background_rect);
+    }
+
+</pre>
+<p>&nbsp;</p>
+<p>Note that this sub first combines all the bitmaps, using a blit
+(&quot;Block Image Transfer&quot;) operation -- which is quite fast, but does
+not update the display.</p>
+<p>The combined image is displayed in the last line. This process of
+combining first, and displaying later, avoids that annoying fading
+between cycles (&quot;flickering&quot;).</p>
+<p>Finally, add the following lines to the end of the main loop, so that
+we call the <code>draw()</code> function with the correct spaceship
+coordinates:</p>
+<p>&nbsp;</p>
+<pre>    while ( $height &gt; 0 ) {
+
+        # ...
+
+        draw( 100, $height );
+        $app-&gt;delay(10);
+    }
+
+</pre>
+<p>&nbsp;</p>
+<p>That's it!</p>
+<p>Run the program and watch the spaceship landing safely on the surface
+of the moon.</p>
+
+</div>
+<h1 id="COPYRIGHT_amp_LICENSE">COPYRIGHT &amp; LICENSE</h1><p><a href="#TOP" class="toplink">Top</a></p>
+<div id="COPYRIGHT_amp_LICENSE_CONTENT">
+<p>Copyright 2009 Nelson Ferraz, all rights reserved.</p>
+<p>This program is free software; you can redistribute it and/or modify it
+under the same terms as Perl itself.</p>
+
+</div>
+</div>
\ No newline at end of file
diff --git a/pages/SDL-Tutorial-Pong.html-inc b/pages/SDL-Tutorial-Pong.html-inc
new file mode 100644 (file)
index 0000000..a0e0d9a
--- /dev/null
@@ -0,0 +1,166 @@
+<div class="pod">
+<!-- INDEX START -->
+<h3 id="TOP">Index</h3>
+
+<ul><li><a href="#PONG_TUTORIAL">PONG TUTORIAL</a>
+<ul><li><a href="#Part_1_We_start_with_a_Rect">Part 1: We start with a Rect</a></li>
+<li><a href="#Part_0_quot_The_Screen_quot">Part 0: &quot;The Screen&quot;</a>
+<ul><li><a href="#Creating_an_empty_event_loop">Creating an (empty) event loop</a></li>
+</ul>
+</li>
+<li><a href="#Part_1_cont_Drawing_our_Rect_on_the_">Part 1 (cont.) - Drawing our Rect on the screen</a></li>
+<li><a href="#Part_2_Our_first_event_tracking_user">Part 2 - Our first event: tracking user movement</a>
+<ul><li><a href="#Hey_don_t_move_away_from_the_court_O">Hey, don't move away from the court! Our first collision detection.</a></li>
+</ul>
+</li>
+<li><a href="#Part_3_Enter_quot_the_Ball_quot">Part 3 - Enter &quot;the Ball&quot;</a>
+<ul><li><a href="#Some_vetorial_background">Some vetorial background</a></li>
+</ul>
+</li>
+<li><a href="#Part_4_Collision_Detection">Part 4 - Collision Detection</a></li>
+<li><a href="#Part_5_Our_hero_s_nemesis_appears">Part 5 - Our hero's nemesis appears</a>
+<ul><li><a href="#really_basic_IA">(really) basic IA</a></li>
+</ul>
+</li>
+<li><a href="#Part_6_Counting_and_showing_the_scor">Part 6 - Counting (and showing) the score</a>
+</li>
+</ul>
+</li>
+</ul><hr />
+<!-- INDEX END -->
+
+<h1 id="PONG_TUTORIAL">PONG TUTORIAL</h1><p><a href="#TOP" class="toplink">Top</a></p>
+<div id="PONG_TUTORIAL_CONTENT">
+<p>This tutorial is intended to help you build your very own version of the Pong game and/or variations of it, using SDL Perl.</p>
+<p>Just in case you live under a rock, Pong is one of the earliest arcade games, a true classic by Atari Inc. The game has two simple rectangles scrolling up and down trying to hit a (square) ball that bounces around, and could be thought of as a table tennis simulation.</p>
+
+</div>
+<h2 id="Part_1_We_start_with_a_Rect">Part 1: We start with a Rect</h2>
+<div id="Part_1_We_start_with_a_Rect_CONTENT">
+<p>In Pong, the player controls a rectangle that moves up and down, so creating the rectangle looks like a good place to start:</p>
+<p>&nbsp;</p>
+<pre>   my $player = SDL::Game::Rect-&gt;new({
+                       -top    =&gt; 10,
+                       -left   =&gt; 20,
+                       -width  =&gt; 6,
+                       -height =&gt; 32,
+                });
+
+</pre>
+<p>&nbsp;</p>
+<p>That creates a new <cite>SDL::Game::Rect</cite> object, a rectangle, with the given width/height dimensions and in the given top/left position of the screen.</p>
+<p>Wait. Did I say... <i>&lt;screen</i>&gt;?</p>
+
+</div>
+<h2 id="Part_0_quot_The_Screen_quot">Part 0: &quot;The Screen&quot;</h2>
+<div id="Part_0_quot_The_Screen_quot_CONTENT">
+<p>In SDL Perl, creating a window screen is very easy and straightforward:</p>
+<p>&nbsp;</p>
+<pre>  use SDL;
+  use SDL::App;
+
+  my $app = SDL::App-&gt;new(
+                 -title  =&gt; 'Pong',  # set window title
+                 -width  =&gt; 640,     # window width
+                 -height =&gt; 480,     # window height
+          );
+
+</pre>
+<p>&nbsp;</p>
+<p>That's it. If you run this code, you'll see a window appear and disappear almost instantly. Why doesn't it stay up? Well, the code is processed linearly, like usual programs are, and with no hidden magic. So, you basically said &quot;create a window&quot; and then the program ended - destroying the window. In order to keep it up and running, listening for events, you need an event loop. </p>
+
+</div>
+<h3 id="Creating_an_empty_event_loop">Creating an (empty) event loop</h3>
+<div id="Creating_an_empty_event_loop_CONTENT">
+<p>An event loop is a simple infinite loop that captures events (like a key pressed or released from the keyboard, mouse movement, etc) and either does something about it or dispatches it to any object that might.</p>
+<p>For this simple game we don't need a very sofisticated event loop, so let's create a simple one.</p>
+<p>&nbsp;</p>
+<pre>  event_loop() while 1;
+
+</pre>
+<p>&nbsp;</p>
+<p>Yay, an infinite loop! Now we are free to define our very own event loop any way we want. Let's make it an empty sub for starters:</p>
+<p>&nbsp;</p>
+<pre>  sub event_loop {
+  }
+
+</pre>
+<p>&nbsp;</p>
+<p>Ok. If you run it, you'll see your <code>$app</code> window displayed until you force to shutdown the program by typing <code>Ctrl-C</code> or something. Other than that, our event loop doesn't do anything, </p>
+
+</div>
+<h2 id="Part_1_cont_Drawing_our_Rect_on_the_">Part 1 (cont.) - Drawing our Rect on the screen</h2>
+<div id="Part_1_cont_Drawing_our_Rect_on_the_-2">
+<p># TODO</p>
+
+</div>
+<h2 id="Part_2_Our_first_event_tracking_user">Part 2 - Our first event: tracking user movement</h2>
+<div id="Part_2_Our_first_event_tracking_user-2">
+<p># TODO</p>
+<p>Now let's query some events!</p>
+<p>First, we need to use the <cite>SDL::Event</cite> module. Add this to the beginning of our code:</p>
+<p>&nbsp;</p>
+<pre>  use SDL::Event;
+  my $event = SDL::Event-&gt;new;
+
+</pre>
+<p>&nbsp;</p>
+
+
+
+<p>Now let's rewrite the <code>event_loop</code> subroutine to take advantage of our event object. The new subroutine should look like this:</p>
+<p>&nbsp;</p>
+<pre>  sub event_loop {
+      # first we poll if an event occurred...
+      while ($event-&gt;poll) {
+
+          # if there is an event, we check its type
+          my $type = $event-&gt;type
+
+          # handle window closing
+          exit if $type == SDL_QUIT;
+      }
+  }
+
+</pre>
+<p>&nbsp;</p>
+<p>#TODO</p>
+
+</div>
+<h3 id="Hey_don_t_move_away_from_the_court_O">Hey, don't move away from the court! Our first collision detection.</h3>
+<div id="Hey_don_t_move_away_from_the_court_O-2">
+
+</div>
+<h2 id="Part_3_Enter_quot_the_Ball_quot">Part 3 - Enter &quot;the Ball&quot;</h2>
+<div id="Part_3_Enter_quot_the_Ball_quot_CONT">
+<p>#TODO</p>
+
+</div>
+<h3 id="Some_vetorial_background">Some vetorial background</h3>
+<div id="Some_vetorial_background_CONTENT">
+<p>#TODO</p>
+
+</div>
+<h2 id="Part_4_Collision_Detection">Part 4 - Collision Detection</h2>
+<div id="Part_4_Collision_Detection_CONTENT">
+<p>#TODO</p>
+
+</div>
+<h2 id="Part_5_Our_hero_s_nemesis_appears">Part 5 - Our hero's nemesis appears</h2>
+<div id="Part_5_Our_hero_s_nemesis_appears_CO">
+<p>#TODO</p>
+
+</div>
+<h3 id="really_basic_IA">(really) basic IA</h3>
+<div id="really_basic_IA_CONTENT">
+<p>#TODO</p>
+
+</div>
+<h2 id="Part_6_Counting_and_showing_the_scor">Part 6 - Counting (and showing) the score</h2>
+<div id="Part_6_Counting_and_showing_the_scor-2">
+<p>#TODO
+</p>
+
+</div>
+</div>
\ No newline at end of file
diff --git a/pages/SDL-Tutorial-Tetris.html-inc b/pages/SDL-Tutorial-Tetris.html-inc
new file mode 100644 (file)
index 0000000..c4d9f6a
--- /dev/null
@@ -0,0 +1,65 @@
+<div class="pod">
+<!-- INDEX START -->
+<h3 id="TOP">Index</h3>
+
+<ul><li><a href="#NAME">NAME</a>
+<ul><li><a href="#The_Overall_view">The Overall view</a>
+<ul><li><a href="#The_Game_Loop">The Game Loop</a></li>
+<li><a href="#The_Game_Logic">The Game Logic</a>
+</li>
+</ul>
+</li>
+</ul>
+</li>
+</ul><hr />
+<!-- INDEX END -->
+
+<h1 id="NAME">NAME</h1><p><a href="#TOP" class="toplink">Top</a></p>
+<div id="NAME_CONTENT">
+<p>Let's Make Tetris</p>
+
+</div>
+<h2 id="The_Overall_view">The Overall view</h2>
+<div id="The_Overall_view_CONTENT">
+<p>All games are a while loop. So we will have something like this.</p>
+
+</div>
+<h3 id="The_Game_Loop">The Game Loop</h3>
+<div id="The_Game_Loop_CONTENT">
+<pre> package Tetris;
+
+ sub run_game_fun_times
+ {
+  while(1)
+  {
+   #game logic here
+  }
+ }     
+
+</pre>
+<p>You need more code you say? Ok well, a game does two things more. </p>
+
+</div>
+<h3 id="The_Game_Logic">The Game Logic</h3>
+<div id="The_Game_Logic_CONTENT">
+<dl>
+       <dt>Input Events</dt>
+       <dd>
+               <p>A game essentially move objects (boxes, monsters so on) in time.</p>
+               <p>
+                       <dl>
+                               <dt>Time</dt>
+                               <dd>
+                                       <p>In SDL time is measured in ticks.</p>
+                               </dd>
+                               <dt>User Input</dt>
+                       </dl>
+               </p>
+       </dd>
+       <dt>Draw Everything</dt>
+</dl>
+<p>--Kartik
+</p>
+
+</div>
+</div>
\ No newline at end of file
index d16d709..26532a2 100644 (file)
@@ -1,2 +1,2 @@
 <div class="pod">
-<h1>Documentation (latest development branch)</h1><a href="SDL.html">SDL</a><br /><a href="SDL-App.html">SDL::App</a><br /><a href="SDL-Cdrom.html">SDL::Cdrom</a><br /><a href="SDL-Color.html">SDL::Color</a><br /><a href="SDL-Cookbook.html">SDL::Cookbook</a><br /><a href="SDL-Cookbook-PDL.html">SDL::Cookbook::PDL</a><br /><a href="SDL-Cursor.html">SDL::Cursor</a><br /><a href="SDL-Event.html">SDL::Event</a><br /><a href="SDL-Events.html">SDL::Events</a><br /><a href="SDL-Font.html">SDL::Font</a><br /><a href="SDL-Game-Palette.html">SDL::Game::Palette</a><br /><a href="SDL-MPEG.html">SDL::MPEG</a><br /><a href="SDL-Mixer.html">SDL::Mixer</a><br /><a href="SDL-MultiThread.html">SDL::MultiThread</a><br /><a href="SDL-Music.html">SDL::Music</a><br /><a href="SDL-OpenGL.html">SDL::OpenGL</a><br /><a href="SDL-Overlay.html">SDL::Overlay</a><br /><a href="SDL-Palette.html">SDL::Palette</a><br /><a href="SDL-PixelFormat.html">SDL::PixelFormat</a><br /><a href="SDL-Rect.html">SDL::Rect</a><br /><a href="SDL-SFont.html">SDL::SFont</a><br /><a href="SDL-SMPEG.html">SDL::SMPEG</a><br /><a href="SDL-Sound.html">SDL::Sound</a><br /><a href="SDL-Surface.html">SDL::Surface</a><br /><a href="SDL-TTFont.html">SDL::TTFont</a><br /><a href="SDL-Timer.html">SDL::Timer</a><br /><a href="SDL-Tool-Font.html">SDL::Tool::Font</a><br /><a href="SDL-Tool-Graphic.html">SDL::Tool::Graphic</a><br /><a href="SDL-Tutorial.html">SDL::Tutorial</a><br /><a href="SDL-Video.html">SDL::Video</a><br /><a href="SDL-VideoInfo.html">SDL::VideoInfo</a><br /></div>
+<h1>Documentation (latest development branch)</h1><a href="SDL.html">SDL</a><br /><a href="SDL-App.html">SDL::App</a><br /><a href="SDL-Cdrom.html">SDL::Cdrom</a><br /><a href="SDL-Color.html">SDL::Color</a><br /><a href="SDL-Cookbook.html">SDL::Cookbook</a><br /><a href="SDL-Cookbook-PDL.html">SDL::Cookbook::PDL</a><br /><a href="SDL-Cursor.html">SDL::Cursor</a><br /><a href="SDL-Event.html">SDL::Event</a><br /><a href="SDL-Events.html">SDL::Events</a><br /><a href="SDL-Font.html">SDL::Font</a><br /><a href="SDL-Game-Palette.html">SDL::Game::Palette</a><br /><a href="SDL-MPEG.html">SDL::MPEG</a><br /><a href="SDL-Mixer.html">SDL::Mixer</a><br /><a href="SDL-MultiThread.html">SDL::MultiThread</a><br /><a href="SDL-Music.html">SDL::Music</a><br /><a href="SDL-OpenGL.html">SDL::OpenGL</a><br /><a href="SDL-Overlay.html">SDL::Overlay</a><br /><a href="SDL-Palette.html">SDL::Palette</a><br /><a href="SDL-PixelFormat.html">SDL::PixelFormat</a><br /><a href="SDL-Rect.html">SDL::Rect</a><br /><a href="SDL-SFont.html">SDL::SFont</a><br /><a href="SDL-SMPEG.html">SDL::SMPEG</a><br /><a href="SDL-Sound.html">SDL::Sound</a><br /><a href="SDL-Surface.html">SDL::Surface</a><br /><a href="SDL-TTFont.html">SDL::TTFont</a><br /><a href="SDL-Timer.html">SDL::Timer</a><br /><a href="SDL-Tool-Font.html">SDL::Tool::Font</a><br /><a href="SDL-Tool-Graphic.html">SDL::Tool::Graphic</a><br /><a href="SDL-Tutorial.html">SDL::Tutorial</a><br /><a href="SDL-Tutorial-Animation.html">SDL::Tutorial::Animation</a><br /><a href="SDL-Tutorial-Images.html">SDL::Tutorial::Images</a><br /><a href="SDL-Tutorial-LunarLander.html">SDL::Tutorial::LunarLander</a><br /><a href="SDL-Tutorial-Pong.html">SDL::Tutorial::Pong</a><br /><a href="SDL-Tutorial-Tetris.html">SDL::Tutorial::Tetris</a><br /><a href="SDL-Video.html">SDL::Video</a><br /><a href="SDL-VideoInfo.html">SDL::VideoInfo</a><br /></div>
diff --git a/tools/PM-Pod2html-snippet.pl b/tools/PM-Pod2html-snippet.pl
new file mode 100644 (file)
index 0000000..816558f
--- /dev/null
@@ -0,0 +1,59 @@
+#!/usr/bin/env perl
+
+use strict;
+use warnings;
+
+use File::Spec;
+use Pod::Xhtml;
+
+#system('git pull');
+
+my $input_path   = 'C:/SDL_perl/lib/pods';
+my $output_path  = 'F:/htdocs/SDL-Site/pages';
+my $parser       = Pod::Xhtml->new(FragmentOnly => 1);
+my %module_names = ();
+my $fh;
+
+read_file($input_path);
+
+# creating index file
+open($fh, '>', File::Spec->catfile($output_path, 'documentation.html-inc'));
+binmode($fh, ":utf8");
+print($fh "<div class=\"pod\">\n<h1>Documentation (latest development branch)</h1>");
+for my $module_name (sort keys %module_names)
+{
+       print($fh '<a href="' . $module_names{$module_name} . '">',
+                 $module_name, 
+                 '</a><br />'
+       );
+}
+print($fh "</div>\n");
+close($fh);
+
+sub read_file
+{
+       my $path = shift;
+       my @files      = <$path/*>;
+
+       foreach(@files)
+       {
+               read_file($_) if(-d $_);
+
+               if($_ =~ /\.pod$/i)
+               {
+                       my $file_name   = $_;
+                          $file_name   =~ s/^$input_path\/*//;
+                       my $module_name = $file_name;
+                          $module_name =~ s/\//::/g;
+                          $module_name =~ s/(\.pm|\.pod)$//i;
+                          $file_name   =~ s/\//-/g;
+                          $file_name   =~ s/(\.pm|\.pod)$/.html-inc/i;
+                       my $file_path   = $file_name;
+                          $file_path   =~ s/\-inc$//;
+                       $module_names{$module_name} = $file_path;
+                          $file_name   = File::Spec->catfile($output_path, $file_name);
+
+                       $parser->parse_from_file($_, $file_name);
+               }
+       }
+}
diff --git a/tools/RSS2html-snippet.pl b/tools/RSS2html-snippet.pl
new file mode 100644 (file)
index 0000000..5a5b59e
--- /dev/null
@@ -0,0 +1,139 @@
+#!/usr/bin/env perl
+
+use strict;
+use warnings;
+use utf8;
+
+use File::Spec::Functions qw(rel2abs splitpath splitdir catpath catdir catfile canonpath);
+use XML::Feed;
+
+my $feed            = XML::Feed->parse(URI->new('http://yapgh.blogspot.com/feeds/posts/default?alt=rss'))
+                      or die XML::Feed->errstr;
+
+my ($volume, $dirs) = splitpath(rel2abs(__FILE__));
+
+my @directories     = splitdir(canonpath($dirs));
+pop(@directories);
+my $parent_dir      = catpath($volume, catdir(@directories));
+my $output_path     = catdir($parent_dir, 'pages');
+
+die("Error: Output path '$output_path' not found.") unless(-d $output_path);
+
+my $fh;
+my %available_tags  = (); # tags to filenames
+my %tag_overview    = (); # tags to short content
+
+printf("path for placing files is: %s\n", $output_path);
+
+my $i = 1;
+for my $entry ($feed->entries)
+{
+    my $output_file = sprintf("blog-%04d.html-inc", $i);
+    my @tags        = $entry->tags;
+       
+    foreach my $tag (sort @tags)
+    {
+       @{$available_tags{$tag}} = () unless defined ($available_tags{$tag});
+       push(@{$available_tags{$tag}}, $output_file);
+    }
+
+       open($fh, '>', catfile($output_path, $output_file));
+       binmode($fh, ":utf8");
+       print($fh "<div class=\"blog\">\n<h1 id=\"NAME\">\n",
+                 $entry->title, 
+                 "\n</h1>\n<div class=\"CONTENT\">\n", 
+                 $entry->content->body, 
+                         "</div>",
+                 "</div>"
+       );
+       close($fh);
+       
+       printf("created file: %s\n", $output_file);
+
+       $i++;
+}
+
+open($fh, '>', catfile($output_path, 'blog-0000.html-inc'));
+binmode($fh, ":utf8");
+print($fh "<div class=\"blog\"><h1>Articles</h1>\n");
+$i = 1;
+for my $entry ($feed->entries)
+{
+       my $tag_links = '';
+    my @tags      = $entry->tags;
+    foreach my $tag (sort @tags)
+    {
+               my $_tag   = $tag;
+                  $_tag   =~ s/\W/-/g;
+       $tag_links .= sprintf(' <a href="tags-%s.html" style="font-size: 10px">[%s]</a>', $_tag, $tag);
+    }
+
+       my $text = $entry->content->body;
+          $text = $1 if $text =~ /^<div.+<\/div>(.+)<div.+<\/div>$/;
+          $text =~ s/<br\s*\/{0,1}>/\n/g;
+          $text =~ s/<[@#%\w\s"\/?&=:\-\.;']+>/ /g;
+          $text =~ s/^\n*//g;
+          $text =~ s/\n*$//g;
+          $text =~ s/\n+/\n/g;
+          $text =~ s/\n/<br \/>/g;
+          $text = $1 if $text =~ /^([^<>]+<br \/>[^<>]+<br \/>[^<>]+<br \/>).*$/;
+          $text =~ s/(<br \/>)+$//g;
+          
+       # overview of all blog entries
+       printf($fh '<div>'
+                    . '<a href="blog-%04d.html">%s</a><br />'
+                    . '<span style="font-size: 10px">%s</span><br />'
+                    . '<span style="font-size: 10px">Tags:</span>%s<br />'
+                            . '%s<br /><a href="blog-%04d.html" style="font-size: 12px">[more]</a><br /><br />'
+                        . '</div>'
+                        . '<hr />',
+               $i, $entry->title, $entry->issued->strftime('%A, %d %B %Y'), $tag_links, $text, $i
+       );
+
+       # preparing the %tag_overview hash for tag-overview-pages
+    @tags      = $entry->tags;
+    foreach my $tag (sort @tags)
+    {
+       @{$tag_overview{$tag}} = () unless defined ($tag_overview{$tag});
+       push(@{$tag_overview{$tag}}, 
+                       sprintf('<div>'
+                                        . '<a href="blog-%04d.html">%s</a><br />'
+                                        . '<span style="font-size: 10px">%s</span><br />'
+                                        . '<span style="font-size: 10px">Tags: %s</span><br />'
+                                        . '%s<br /><a href="blog-%04d.html" style="font-size: 12px">[more]</a><br /><br />'
+                                . '</div>',
+                       $i, $entry->title, $entry->issued->strftime('%A, %d %B %Y'), $tag_links, $text, $i
+               ));
+    }
+
+       $i++;
+}
+print($fh "</div>\n");
+close($fh);
+printf("created file: %s\n", 'blog-0000.html-inc');
+
+
+# csv: "tagname: file1,file2\n"
+open($fh, '>', catfile($output_path, 'tags-index'));
+binmode($fh, ":utf8");
+foreach my $tag (sort keys %available_tags)
+{
+       printf($fh "%s: %s\n", $tag, join(',', @{$available_tags{$tag}}));
+}
+close($fh);
+printf("created file: %s\n", 'tags-index');
+
+# overview pages for tags
+foreach my $tag (sort keys %tag_overview)
+{
+       my $_tag = $tag;
+       $_tag =~ s/\W/-/g;
+       open($fh, '>', catfile($output_path, 'tags-' . $_tag . '.html-inc'));
+       binmode($fh, ":utf8");
+       print($fh '<div class="blog"><h1>Results for tag: ' . $tag . '</h1>' 
+               . join('<hr />', @{$tag_overview{$tag}})
+                       . '</div>');
+       close($fh);
+       printf("created file: %s\n", 'tags-' . $_tag . '.html-inc');
+}
+