NAME

App::Plog - The one and a half minute blog

SYNOPSIS

use App::Plog ;

App::Plog::create_blog(@ARGV) ;

exit(0)  ;

DESCRIPTION

Generate a rudimentary HTML blog.

DOCUMENTATION

This module installs a script that allow you to generate a rudimentary blog using your prefered editor and the command line. This file documents the inner workings of the module.

Further documentation, useful to the user is displayed by running the plog end user application:

$> plog --help

ARCHITECTURAL OVERVIEW

App::Plog purpose is to transform input blocks, in a well defined format, to HTML snippets that are aggregated to form a single HTML file blog you can publish. The application itself is very simple as it delegates almost every action it takes to specialized modules. The modules can be completely replaced or inherited from to tune them.

The default modules used by App::Plog are all defined inline within the App::Plog module. This document describes the working of those default modules.

Overview

******************     .-----------------------.
*      RCS       *     |  Extension matching   |
******************     |-----------------------|
* .-------.      *     |   .--------------.    |   .----------.   ************
* | .-------.    *     |   | pod renderer |    |   | .----------. *   HTML   *
* '-| .-------.  *  .->|   '--------------'    |-->| | rendered | * template *
*   '-| entry |  *  |  | .-------------------. |   '-|  entry   | ************
*     '-------'  *  |  | | Asciidoc renderer | |     '----------'       |
******************  |  | '-------------------' |           |            |
         |          |  '-----------------------'           |            |
         v          |                                      |            |
   .-----------.    |                                      |            |
   | .-----------.  |                                      v            v
   | | raw data  |  |   .----------------------.   .-----------------------.
   | |    +      |--'-->|    feed generator    |   |      aggregator       |
   '-| RCS data  |      '----------------------'   '-----------------------'
     '-----------'                  |                          |
                                    |                          |
                                    |                          |
**************************   .------|--------------------------|-------.
*     blog elements      *   |      |       tmp directory      |       |
**************************   |------|--------------------------|-------|
* .-------.   .-----.    *   |      v                          v       |
* | image |.  | css |    *   | .----------.              .-----------. |
* '-------'|  '-----'--. *   | | feed.xml |              | blog.html | |
*  '-------'     | ... | *   | '----------'              '-----------' |
*                '-----' *   |                                         |
**************************   '-----------------------------------------'
             |                                    |
             |                                    |      ********************
             |       .-------------------.        |      * note: input data *
             '------>| publishing script |<-------'      *  is in box with  *
                     '-------------------'               *    star border   *
                                                         ********************

Blog configuration

Each blog has a specific configuration which allows you to fine tune the default behavior or override it. The elements used by App::Plog are defined within the blog configuration file so you can use your own modules or specialize the default modules.

The blog configuration is a perl data structure looking like:

 {
 commands =>
  {
  class => 'App::Plog::Commands',
  },
  
 rcs =>
  {
  class => 'App::Plog::RCS::Git',
  entry_directory => '/where/the/blogs/entries/git/repository/is',
  },
 
 renderer =>
  {
  class => 'App::Plog::Renderer::Extension',
     
  renderers =>
   {
   # match the entry file extension to the specialized renderer
   # using perl regex
   '.pod$' =>
    {
    class => 'App::Plog::Renderer::HTML::Pod',
    css => 'sco.css' # make it look like search.cpan.org
    },
   '.txt$' =>
    {
    class => 'App::Plog::Renderer::HTML::Asciidoc',
    },
   '.' => # default to pod
    {
   class => 'App::Plog::Renderer::HTML::Pod',
   css => 'sco.css'
   },
  },
 },
 
 aggregator =>
  {
  class => 'App::Plog::Aggregator::Template::Inline',
  
  # information passed to the Aggregator
  template => 'frame.html',
  feed_tag => 'FEED_TAG',
  entries_tag => 'ENTRIES_TAG',
  result_file => 'plog.html',
  },
 
 feed =>
  {
  class => 'App::Plog::Feed::Atom',
  page => 'http://your_server/your_blog/your_plog.html', 
  } ,
	
 # used in the update sub
 destination_directory => '/some/directory/to/publish/your_blog/in',
 
 #relative to blog root directory, can contain css, images, ...
 elements_directory => 'elements', 
 
 update_script => 
  'update_blog.pl', # or shell script, bat file, ...
  # or
  sub
   {
   my ($configuration, $blog_directory, $temporary_directory) = @_ ;
   
   my $elements_directory 
     = "$blog_directory/$configuration->{elements_directory}/*" ;
   
   ...
   
   },
 }

Commands

The default commands are defined within the App::Plog::Commands package. You can add or remove commands from the plog application by deriving from App::Plog::Commands or writing a new module.

Revision control system

The default RCS is git. App::Plog::RCS::Git implements the interface needed by App::Plog. Other RCS are possible as well as a plain file system backend. I'll be happy to add another RCS to the distribution.

Renderers

Transform input blocks to HTML snippets is handled, at the top level, by App::Plog::Renderer::Extension. App::Plog::Renderer::Extension doesn't render the input blocks directly; it matches the input block file extension to a specialized renderer and runs it. See section renderer in the configuration.

Two input formats are supported in the distribution, Pod and Asciidoc. Other format can easily be added.

Agregator

The default aggregator is implemented in App::Plog::Aggregator::Template::Inline. App::Plog::Aggregator::Template::Inline simply replaces user defined tags with the rendered HTML snippets in a template of you choosing. The template and tags are defined in the configuration in section aggregator.

Feed

If section feed is defined, the feed generator, Package App::Plog::Feed::Atom in the default configuration, generates an Atom feed file. The aggregator also checks for the generation of a feed and inserts a feed link and icon in the template.

Publishing the blog

The blog is published, made available to people other than the author, or just the author if you so wish, by a user defined script or perl sub defined in the blog configuration.

SUBROUTINES/METHODS

The subroutines and methods are listed below for each package

App::Plog SUBROUTINES/METHODS

create_blog(@arguments)

create_blog will parse the command line and execute the the plog command.

use App::Plog ;
App::Plog::create_blog(@ARGV) ;
exit(0) ;

Arguments

@arguments - the arguments passed on the command line

Returns - Nothing

Exceptions - Croaks on bad commands

parse_configuration(@arguments)

 my ($command, $arguments, $configuration, $blog_id, $blog_directory, $blog_configuration_file, $blog_configuration, $temporary_directory)
	= parse_configuration(@arguments) ;

The global plog configuration is located in ~:.plog but can be overridden by the --configuration_path option. Arguments

@arguments - command line arguments passed to the plog script in the format
```
$> plog [--option[s]] command [argument] [argument] ...
```

Returns

$command - the command to execute
\@arguments - the arguments to the command to execute
\%configuration - the global plog configuration
$blog_id - the name of the blog to work on. extracted from the global configuration or passed through the --blog_id option
$blog_directory - the directory where the '$blog_id' data are
$blog_configuration_file - the file name of the '$blog_id' configuration
\%blog_configuration - the '$blog_id' plog configuration
$temporary_directory - a temporary directory created during the run of the script or the directory passed thought the --temporary_directory option

Exceptions

Invalid options
missing configuration files
errors in configuration files

display_help()

Arguments - None

Returns - Exits the process with value 0 (zero).

Exceptions - Croaks on perldoc errors

App::Plog::Commands SUBROUTINES/METHODS

new(\%options)

Arguments

\%options - the command section from the blog configuration file

Returns - a App::Plog::Command object

Exceptions -None

command_exists(...)

Arguments- string - command name

Returns - boolean -true if the command is available to run

Exceptions -

run_command(...)

Arguments- see Returns in sub parse_configuration

Returns - Nothing

Exceptions - command if the command is neither defined nor exists

add_entry(...)

For each argument passed to this command, a file will be created in the current directory based on the blog template. A blog template is a file that matches $blog_directory/entry_template*. The contents are of no importance to plog.

Arguments- see Returns in sub parse_configuration

\@arguments Contains the list of files to create

Returns - Nothing

Exceptions - Croaks if no template is found or more than a template is found

copy_elements(...)

Each argument passed to this command is taken as a file or a directory and will be copied to <$blog_directory/$blog_configuration->{elements_directory}>. A line, for each argument, is output on STDOUT.

Arguments- see Returns in sub parse_configuration

\@arguments Contains the list of files to copy

Returns - Nothing

Exceptions - Croaks if the copy fails

ls_entries()

Lists all the blog entry under version control in $blog_configuration-{rcs}{entry_directory}>.

Arguments- see Returns in sub parse_configuration

Returns - Nothing

Exceptions - Croaks if the RCS object can't be created

ls_blogs(...)

Prints, on stdout, the list of blogs available to plog. where a blog is a directory within $configuration-{plog_root_directory}/>.

Arguments- see Returns in sub parse_configuration

Returns - Nothing

Exceptions

generate_blog(...)

Handles the creation of the blog and its feed, including the creation of the objects defined in the plog configuration.

Arguments- see Returns in sub parse_configuration

Returns - Nothing

Exceptions - Croaks if object needed to generate the blog can't be created

update_blog(...)

Generates the blog and runs the update script defined in $blog_configuration-{update_script}>. The update script usually publishes the blog by copying the necessary data to a web server.

The update script is either a script in the language of your choosing, in which case the following arguments are passed on the command line

$blog_configuration_file
$blog_directory
$temporary_directory

or a perl sub in which case the following arguments are passed to the sub

$blog_configuration
$blog_directory
$temporary_directory

Arguments- see Returns in sub parse_configuration

Returns - Nothing

Exceptions

App::Plog::RCS::Git SUBROUTINES/METHODS

new(\%options)

Arguments

\%options - the rcs section from the blog configuration file

Returns - a App::Plog::RCS::Git object

Exceptions -None

parse($self, $blog_directory, $temporary_directory)

Arguments

$self -
$blog_directory - the path to the blog directory
$temporary_directory - directory where temporary data can be saved

Returns - Nothing

Exceptions

App::Plog::Renderer::Extension SUBROUTINES/METHODS

new(\%options)

Arguments

\%options - the renderer section from the blog configuration file

Returns - an App::Plog::Renderer::Extension object

Exceptions -None

render($self, \%entries, $blog_directory, $temporary_directory)

exit(0) ;

Arguments

$self -
\%entries - entries parsed by the rcs object
$blog_directory - the path to the blog directory
$temporary_directory - directory where temporary data can be saved

Returns - Nothing

Exceptions

App::Plog::Renderer::HTML SUBROUTINES/METHODS

new()

Arguments - None

Returns - Nothing

Exceptions - confess if called. This class serves a base class to derived classes

get_entry_date_html($self, $date)

Arguments

$self -
$date - string in format "2009-10-05 14:53:24 +0200"

Returns - $date in HTML format in three columns

2009-10-05
14:53:24
+0200

Exceptions - None

App::Plog::Renderer::HTML::Pod SUBROUTINES/METHODS

new(\%options)

Arguments

\%options - the section from the blog configuration file where a App::Plog::Renderer::HTML::Pod object was required

Returns - an App::Plog::Renderer::HTML::Pod object

Exceptions -None

render($self, $blog_directory, $temporary_directory, $version, $commit, $text, $date)

Arguments

$self -
$blog_directory - the path to the blog directory
$temporary_directory - directory where temporary data can be saved
$version - number - the version of the blog entry
$commit - the commit id of the blog entry
$text - the text of the entry as it was found by the version control system
$date - string in format "2009-10-05 14:53:24 +0200"

Returns - the pod text rendered to HTML

Exceptions - None

App::Plog::Renderer::HTML::Asciidoc SUBROUTINES/METHODS

new(\%options)

Arguments

\%options - the section from the blog configuration file where a App::Plog::Renderer::HTML::Asciidoc object was required

Returns - an App::Plog::Renderer::HTML::Asciidoc object

Exceptions -None

render($self, $blog_directory, $temporary_directory, $version, $commit, $text, $date)

Arguments

$self -
$blog_directory - the path to the blog directory
$temporary_directory - directory where temporary data can be saved
$version - number - the version of the blog entry
$commit - the commit id of the blog entry
$text - the text of the entry as it was found by the version control system
$date - string in format "2009-10-05 14:53:24 +0200"

Returns - the asciidoc text rendered to HTML

Exceptions - None

App::Plog::Aggregator::Template::Inline SUBROUTINES/METHODS

new(\%options)

Arguments

\%options - the aggregator section from the blog configuration file

Returns - an App::Plog::Aggregator::Template::Inline object

Exceptions -None

aggregate($self, \%entries, $blog_directory, $temporary_directory)

Arguments

$self -
$entries - the entries created by the rcs object and rendered
$blog_directory - the path to the blog directory
$temporary_directory - directory where temporary data can be saved

Returns - Nothing

Exceptions - croaks if template doesn't exist or doesn't contain the tags defined in the configuration.

App::Plog::Feed::Atom SUBROUTINES/METHODS

new(\%options)

Arguments

\%options - the feed section from the blog configuration file

Returns - an App::Plog::Feed::Atom object

Exceptions -None

generate($self, $entries, $blog_directory, $temporary_directory)

$temporary_directory/rss.xml

Arguments

$self -
$entries - the entries created by the rcs object and rendered
$blog_directory - the path to the blog directory
$temporary_directory - directory where temporary data can be saved

Returns - Nothing

Exceptions - None

BUGS AND LIMITATIONS

None so far.

AUTHOR

Nadim ibn hamouda el Khemir
CPAN ID: NKH
mailto: nadim@cpan.org

COPYRIGHT & LICENSE

This program is free software; you can redistribute it and/or modify it under the terms of either:

the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version, or
the Artistic License version 2.0.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc App::Plog

You can also look for information at:

AnnoCPAN: Annotated CPAN documentation

http://annocpan.org/dist/App-Plog
RT: CPAN's request tracker

Please report any bugs or feature requests to L <bug-app-plog@rt.cpan.org>.

We will be notified, and then you'll automatically be notified of progress on your bug as we make changes.
Search CPAN

http://search.cpan.org/dist/App-Plog

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

DOCUMENTATION

ARCHITECTURAL OVERVIEW

Overview

Blog configuration

Commands

Revision control system

Renderers

Agregator

Feed

Publishing the blog

SUBROUTINES/METHODS

App::Plog SUBROUTINES/METHODS

create_blog(@arguments)

parse_configuration(@arguments)

display_help()

App::Plog::Commands SUBROUTINES/METHODS

new(\%options)

command_exists(...)

run_command(...)

add_entry(...)

copy_elements(...)

ls_entries()

ls_blogs(...)

generate_blog(...)

update_blog(...)

App::Plog::RCS::Git SUBROUTINES/METHODS

new(\%options)

parse($self, $blog_directory, $temporary_directory)

App::Plog::Renderer::Extension SUBROUTINES/METHODS

new(\%options)

render($self, \%entries, $blog_directory, $temporary_directory)

App::Plog::Renderer::HTML SUBROUTINES/METHODS

new()

get_entry_date_html($self, $date)

App::Plog::Renderer::HTML::Pod SUBROUTINES/METHODS

new(\%options)

render($self, $blog_directory, $temporary_directory, $version, $commit, $text, $date)

App::Plog::Renderer::HTML::Asciidoc SUBROUTINES/METHODS

new(\%options)

render($self, $blog_directory, $temporary_directory, $version, $commit, $text, $date)

App::Plog::Aggregator::Template::Inline SUBROUTINES/METHODS

new(\%options)

aggregate($self, \%entries, $blog_directory, $temporary_directory)

App::Plog::Feed::Atom SUBROUTINES/METHODS

new(\%options)

generate($self, $entries, $blog_directory, $temporary_directory)

BUGS AND LIMITATIONS

AUTHOR

COPYRIGHT & LICENSE

SUPPORT

SEE ALSO

Module Install Instructions