The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Toader-1.1.1
River stage zero No dependents
++
/ Documentation::Toader

Toader

Common Variables In The Documentation

Below is a list of variables that are commonly used in documentation.

    $entryName - The entry name for a L<Toader::Entry> object.
    $outputDir - This is base directory for writing output to.
    $r2r - This is relative path from root L<Toader> directory to the current one.
    $toaderDir - This is a L<Toader> directory.
    $toaderRoot - This is the root L<Toader> directory.
    $pageName - This is the name of the page.

What is a Toader directory?

A Toader directory is a directory with a '.toader' directory in it. The Toader root is base Toader directory in a tree of Toader directories.

The following limitations are imposed on what can be a Toader directory.

First it can't be root, '/'.

Second, it can't begin with a period.

Third, it must be able to contain a '.toader' directory.

Below is a posibility of what a '.toader' directory may contain as well as the mapping to the relavent documentation.

    autodoc/ - AutoDoc.pod
    config.ini - Config.pod
    entries/ - Entry.pod
    gallery.ini - Gallery.pod
    index - Directory.pod
    pages/ - Pages.pod
    templates/ - Templates.pod

Common Objects

AutoDoc

This copies over documentation from the specified directories under the specified directories under the Toader directory.

The related modules are as below.

Toader::AutoDoc

Toader::Render::AutoDoc

Toader::Render::AutoDoc::Cleanup

Directory

This is a Toader directory. It renders to a single page that acts a index/landing page for a directory.

The related modules are as below.

Toader::Directory

Toader::Render::Directory

Toader::Render::Directory::Cleanup

Toader::Render::Directory::backends::html

Entry

Entries are basically a blog entry or a article in a Toader directory.

By default the last entries page will the 25 newest articles.

The related modules are as below.

Toader::Entry

Toader::Render::Entry

Toader::Render::Entry::Cleanup

Toader::Render::Entry::backends::html

This is handles for Toader.

The related modules are as below.

Toader::Gallery

Toader::Render::Gallery

Page

This is a single named page. It is for creating like a about page, contact page, etc.

The related modules are as below.

Toader::Page

Toader::Render::Page

Toader::Render::Page::Cleanup

Toader::Render::Page::backends::html

Rendering

Rendering is handled be done via two methods, if not doing it via the command line tools.

The first is to use Toader::Render. This is the simpler method as once initiated Toader::Render can be reused.

The second is to invoke the rendering module for that type of object directly and use it to render it. For some things this is required as there are

The template "page" is used for rendering all pages. It is as below.

    <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
    <html>
    
      <head>
        <title> [== $c->{_}->{siteTitle} ==] </title>
        <LINK href="[== $g->cssLocation ==]" rel="stylesheet" type="text/css">
      </head>
    
      <body>
    
        <div id="header" >
          [== $g->top ==]
        </div>
    
        <div id="location" >
          [== $g->locationbar( $locationID ) ==]
        </div>
    
        <div>
    
          <div id="sidebar" >
                [==
                  if ( ! $g->hasEntries ){
                    return "";
                  }
              return "          <h3>Entries</h3>\n".
                  "             ".$g->entriesLink." <br>\n".
                  "             ".$g->entriesArchiveLink." <br>\n".
                  "             <hr>\n";
                ==]
                [==
                  my $pages=$g->listPages;
                  if ( ( ! defined( $pages ) ) || ( $pages eq "" ) ){
                    return "";
                  }
                  return "              <h3>".$g->pageSummaryLink."</h3>\n".$pages."\n          <hr>\n";
                ==]
                <h3>Directories</h3>
                [== 
                        if ( $g->atRoot ){
                                return "";
                        }
                        return $g->rlink("Go To The Root")."            <br>\n          ";
                               $g->upOneDirLink."               <br>\n          <br>";
                ==]
    
                [== $g->listDirs ==]
          </div>
    
          <div id="maincontent" >
                [== $content ==]
          </div>
    
        </div>
        
        <br><br><br>
        
        <div id="copyright">
          [==
            my ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst)=localtime(time);
            $year=$year+1900;
            return "Copyright ".$year." ".$c->{_}->{owner};
          ==]
        </div>
    
      </body>
    </html>

The following variables are passed to it.

    toader - The L<Toader> object.
    g - The L<Toader::Render::General> object.
    self - The L<Toader::Render::Entry> object.
    obj - The L<Toader::Entry> object.
    c - The L<Config::Tiny> holding the Toader config.
    content - This is the content to be included in the content section of the page.

VCS integration

Toader is meant to integrate with a versioning system. By storing everything as a file, this is a fairly trivial task.

This allows the website to easily be stored in the same place and manner as the coding project that it is a website for, which allows documentation to be published easily and automatically via Toader::AutoDoc .

Security Concerns

As Toader uses Perl for templating, this means any arbitrary could can be executed via rendering it. For this purpose it is important that the person doing the rendering trusts that nothing dangerous is in any of it. For this purpose one needs to trust the any one who has commit privledges to that part of the VCS tree that contains it.