#!/usr/bin/perl
use strict;
use warnings;
use utf8;
use Encode qw/decode encode/;
use HTML::Entities;    # Must be installed!

=head1 NAME

B<hidexthtml.pl> -- hide template engine syntax from markdown
processors or HTML Tidy

=head1 SYNOPSIS

In a file I<markdown.txt>:

 <--* This comment will be removed *-->

 Markdown is great but if you want to put
 <!--' <% $template_engine %> '--> syntax
 inside your markdown documents it will
 be garbled.

 but if you put <!--' <% $template_engine %> '-->
 instructions in your markdown text inside some
 specially marked HTML comments

     ## Welcome <!--' <% $user %> "-->!

 you can just filter your markdown.pl output
 through hidexthtml.pl, put your

     use <!--/ <% $template_engine %> /-->;

 at the top of your script and call the
 template!

 ~$ markdown markdown.txt | tidy \
 > | hidexthtml.pl >template.html

In I<template.html>:

 Markdown is great but if you want to put
  <% $template_engine %>  syntax
 inside your markdown documents it will
 be garbled.

 but if you put  <% $template_engine %> 
 instructions in your markdown text inside some
 specially marked HTML comments

     ## Welcome  <% $user %>!

 you can just filter your markdown.pl output
 through hidexthtml.pl, put your

     use <!--/ <% $template_engine %> /-->;

 at the top of your script and call the
 template!

=head1 DESCRIPTION

To have HTML comments totally stripped put an asterisk immediately
after and before the HTML comment tags (i.e. without any intervening
whitespace):

 <--* This comment will be removed *-->

Put single quote characters immediately after and before the HTML
comment tags (i.e. without any intervening whitespace) to be sure to
get at least one space character before and after the template code.

 <!--' Template engine syntax here '-->

Put double quote characters immediately after and before the HTML
comment tags (i.e. without any intervening whitespace) to be not to get
any whitespace characters before and after the template code.

 <!--" Template engine syntax here "-->

Mnemonic: there is nothing between the ticks in a doublequote!

You can combine these two markers to be sure to get a space character
before the template code but not any whitespace after it or vice versa:

 <!--' Space before, no space after "-->

 <!--" No space before, space after '-->

In Markdown text

 `<!--/ Template engine syntax here /-->`

     Paragraph text

     Code block text
     <!--/ Embedded template code /-->
     More codeblock text

     Next paragraph

Put a single slash character after and before

the HTML comment tags if you want to put any template code (or
not-to-be-escaped HTML entities!) inside a Markdown code block or code
.

Mnemonic: Slash HTML escaping inside a comment with slashes!

You can even document this script's C<E<lt>!--/ /--E<gt>> in code
blocks/spans by putting more slashes:

 <!--// foo //-->

will become

 &lt;!--/ foo /--&gt;

 <!--/// foo ///-->

will become

 &lt;!--// foo //--&gt;

and so on.

=head1 AUTHOR

B P Jonsson, C<< <bpjonsson at gmail.com> >>

(Let the Goog filter the spam for me!)

=head1 LICENSE AND COPYRIGHT

Copyright 2010 B P Jonsson.

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; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.

=cut

my %com_ext = (

    spaced   => [ qr{ <!--' \s* | \s* '--> }x, ' ' ],

    unspaced => [ qr{ \s* <!--" \s* | \s* "--> \s* }x, '' ],

    incode =>
      qr{ &lt;!--/ (?! / ) \s* ( .*? ) \s* (?<! / ) /--&gt; }sx,

    showcode =>
      [ qr{ (?<= &lt;!-- / ) / | / (?= / --&gt; ) }x, '' ],
	  remove => [ qr/<!--\* .*? \*--> /x, '' ],
);

my $html;
{
    local $/;    # Slurp mode
                 # Slurp and decode HTML in one go;
    $html = decode( 'utf8', <> );
}

$html =~ s( $com_ext{incode} ){ decode_entities($1) }egx;

for my $com ( @com_ext{ qw/ spaced unspaced showcode remove / } )
{
    $html =~ s/$com->[0]/$com->[1]/g;
}

print encode( 'utf8', $html );

