perldoc-md main file

perldoc-md.pl

#!/usr/bin/env perl

use v5.14;
use warnings;

use File::Spec;
use IO::File;
use autodie;

my ($dir);
BEGIN {
    my (@parts) = File::Spec->splitdir(File::Spec->rel2abs(__FILE__));
    pop(@parts);
    $dir = File::Spec->catdir(@parts);
}
use lib $dir;

require 'Markdown_1.0.1/Markdown.pl';

open(FTD, $ARGV[0]);
my (@lines) = <FTD>;
close(FTD);

local ($1);
my ($atend)    = 0;
my ($inmd)     = 0;
my ($section)  = '';
my ($markdown) = '';

foreach my $line (@lines) {
    if ($line =~ /^__([A-Z0-9_]+)__$/i) {
        $section = $1;
    }
    else {
        $section = '';
    }

    unless ($atend || ($section eq 'END')) {
        next;
    }

    if ($section eq 'END') {
        $atend = 1;
    }

    if ($inmd) {
        if ($section && ($section ne 'MARKDOWN')) {
            $inmd = 0;
            $markdown .= "\n";
        }
        else {
            $markdown .= $line;
        }
    }
    else {
        if ($section && ($section eq 'MARKDOWN')) {
            $inmd = 1;
        }
    }
}

my ($html) = Markdown::Markdown($markdown);
say $html;


# perldoc-md.pl - MIT Licensed by Stephen Belcher, 2012.

__END__
__MARKDOWN__

perldoc-md.pl
=============

Summary
-------

Convert source files with embedded Markdown-flavored documentation into HTML
output files.

Example
-------

    $ cat Module/Example.pm
    use v5.14;
    package Module::Example {
        ...
    }

    __END__
    __MARKDOWN__

    Hey, this is some markdown documentation for `Module::Example`!

    $ perldoc-md.pl Module/Example.pm > module_example.html
    $

Usage
-----

Currently there are no flags, no options, nothing. You must provide a single
filename and it'll spit out HTML. You must embed this in a full HTML
document, the wrappings aren't done for you.

These are all TODO items.

Why? AKA Philosophizing
-----------------------

POD is a huge pain. It's difficult to read, difficult to write, and is
largely something that's supported for historic reasons. Of course, everyone
who's anyone knows POD, so why fix it if it isn't broken?

Well, the two reasons I list *are* its brokenness. It represents a
significant hurdle to people new to the idea of properly documenting their
code, and even after you're well-versed in POD, I can't imagine it's much fun
to write. I've only tried to fully document two of my larger projects, and it
took me longer to write the documentation than it took to write the code.
Let's not even get into how long it took me to update everything if I made
more than the slightest change.

There are things this program doesn't try to do yet, because POD covers a lot
of ground. Far from simply outputting HTML documentation, it also outputs to
man pages, LaTeX, and a dizzying array of other formats. In theory, the
Markdown documentation can also be converted to other formats, but that's not
my goal. My goal is to write documentation that it doesn't hurt my soul to
write. I want to document everything, but I also want to have time to code
more things.