I saw on the "Stages of Perl" website that an Adept writes his own pod2xyz script. I took that as a personal challenge.
So here's a twist on the theme: my first attempt to bypass POD by translating YAML directly to HTML.
#
#
# yaml2html.pl
#
# rje 5 Jan 2005
#
#
use YAML;
use strict;
my $doc = shift || die "SYNOPSIS: ", basename $0, " yaml-doc\n";
my $yaml = readYaml( $doc );
my $level = 1;
my @toc;
my @body;
processRef( $yaml );
print<<HTML;
<html>
<body>
@toc
<hr>
@body
</body>
</html>
HTML
sub readYaml # ugly kludge
{
my $doc = shift;
my @yamlsrc;
open IN, $doc || die "ERROR: Cannot open file $doc\n";
foreach (<IN>)
{
next unless /^-{3}/ .. /^\.{3}/;
push @yamlsrc, $_;
}
close IN;
pop @yamlsrc if $yamlsrc[-1] =~ /^\.{3}/; # remove final EOD
my $yamlsrc = join '', @yamlsrc;
return YAML::Load( $yamlsrc );
}
sub processRef
{
my $yref = shift;
processMapref($yref) if ref($yref) eq 'HASH';
processArrayref($yref) if ref($yref) eq 'ARRAY';
processString($yref) if ref($yref) eq ''; # just a string!
}
sub processMapref
{
my $mapref = shift;
foreach my $key (sort keys %$mapref)
{
my $val = $mapref->{$key};
push @toc, "<li><a href='#$key'>$key</a></li>\n";
push @body, "<li><a name='$key'><h$level>$key</h$level></a></
+li>\n";
$level++;
processRef( $val );
$level--;
}
}
sub processArrayref
{
my $aryref = shift;
push @toc, "<ol>\n";
push @body, "<ul>\n";
foreach my $key (@$aryref)
{
my $val = $key;
processRef( $val );
}
push @body, "</ul>\n";
push @toc, "</ol>\n";
}
sub processString
{
my $str = shift;
my $indent = ' ' x $level;
my @lines = split( "\n", $str );
foreach(@lines)
{
next while /<pre>/ .. /<\/pre>/;
$_ .= '<br>';
}
foreach(@lines)
{
next unless /<pre>/ .. /<\/pre>/;
$_ = $indent . $_ . "\n";
}
push @body, @lines;
}
__END__
---
- yaml2html:
- Version: 0.1
- Author: Robert Eaglestone
- Date: 5 January 2005
- Example: |
<pre> yaml2html.pl [input file] > [html output] </pre>
<pre> yeml2html.pl yaml2html.pl > yaml2html.html </pre>
- Detail:
- Purpose: >
This is a YAML parser which takes its input document
and emits primitive HTML.
- Origins: >
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 a shorthand for relatively simple,
heirarchical markup documentation... 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.
- How to use it:
- Assumptions: I assume you already know the basics of YAML.
- Format: |
Since hashtables are unordered, I find that using arrays
ensures that my sections come out in the order I entered
them. So all section lists, including the root "Chapters",
are arrays. 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.
- What this script does with the text: |
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 an Unordered (Bullet) List.
< br > tags are added before newline characters in the body t
+ext,
except when the text is inside < pre >...< /pre > tags, in wh
+ich
case it's left alone.
...
In reply to yaml2html
by rje