/ 
YAML-Yaml2Html-0.5
++
/ YAML::Yaml2Html

NAME

YAML::Yaml2Html - Builds an HTML page from a YAML-based document.

SYNOPSIS

        use YAML::Yaml2Html;
        
        my $y2h = new YAML::Yaml2Html( $my_document );      
        print $y2h->toString();
        
        OR
        
        my $y2h = new YAML::Yaml2Html();
        $y2h->loadFile( $y2h );
        print $y2h->toString();
        
        OR
        
        my $y2h = new YAML::Yaml2Html();
        $y2h->loadText( "---\ntitle: This is just a test\n..." );
        $y2h->toFile( "myfile" ); 
        # module will auto-append '.html' if it's not already there.

DESCRIPTION

    This uses the YAML parser to convert a specialized YAML document into an HTML page.

    I recently learned POD. Immediately, I was taken by its simplicity. It's so much easier to use than HTML, I even began writing simple HTML documents -- which had nothing to do with Perl -- with POD, then using pod2html to convert to a webbable format.

    After doing this for awhile, I started to realize that POD was simply shorthand for heirarchical text... just the kind of thing that YAML is good for. Well, being rather lazy when it comes to using two tools where a single tool will work fine, I decided to write a proof-of-concept Perl structure parser that could output HTML... a back-end to YAML, in a way.

    Root-level keys (Everything is optional):

       category: document super-title or category title
   
   title: title text goes here      
   
   head: head text goes here (like Javascript)
   
   css: name of a CSS file goes here (this is a convenience tag)
   
   dictionary: a map of acronyms to their definitions
   
      This is a very handy tag.  This is a mapping of acronyms used in the
      document with their definitions.  This module performs a global text
      replacement, with the acronym replaced by the HTML fragment:
      < acronym title="whatever" >ACRONYM< / acronym >
   
   body: list of chapters
   
      Since hashtables are unordered, I find that using arrays
      in the document body ensures that my sections come out in the 
      order I entered them.  So all of the body sections, including the 
      root "Chapters", are lists.  List items themselves are maps 
      or hashtables containing either (1) another list, or (2) text.
      
      The leaf nodes, which necessarily are strings, are mapped
      to their section titles.  Refer to this example to see
      what I mean.

    This script builds a table of contents and a body.

    Sections are titled using < h1 >, < h2 >...< hn >, according to their subordinate level. They're also indented: the table of contents is indented using an Ordered (Numbered) List, and the body is indented using < div id="d##"> tags, where ## is the division number within that level. Paragraphs within text bodies are divided with < p class="p##"> tags, where ## is the paragraph number within that text.

    < br > tags are added before newline characters in the body text, except when the text is inside < pre >...< /pre > tags, in which case it's left alone.

AUTHOR

Robert Eaglestone

COPYRIGHT

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AVAILABILITY

The latest version of this library is likely to be available from CPAN.