github-markup 3.0.1 → 3.0.2

data/vendor/Pod-To-HTML/LICENSE

@@ -0,0 +1,201 @@
+		       The Artistic License 2.0
+
+	    Copyright (c) 2000-2006, The Perl Foundation.
+
+     Everyone is permitted to copy and distribute verbatim copies
+      of this license document, but changing it is not allowed.
+
+Preamble
+
+This license establishes the terms under which a given free software
+Package may be copied, modified, distributed, and/or redistributed.
+The intent is that the Copyright Holder maintains some artistic
+control over the development of that Package while still keeping the
+Package available as open source and free software.
+
+You are always permitted to make arrangements wholly outside of this
+license directly with the Copyright Holder of a given Package.  If the
+terms of this license do not permit the full use that you propose to
+make of the Package, you should contact the Copyright Holder and seek
+a different licensing arrangement. 
+
+Definitions
+
+    "Copyright Holder" means the individual(s) or organization(s)
+    named in the copyright notice for the entire Package.
+
+    "Contributor" means any party that has contributed code or other
+    material to the Package, in accordance with the Copyright Holder's
+    procedures.
+
+    "You" and "your" means any person who would like to copy,
+    distribute, or modify the Package.
+
+    "Package" means the collection of files distributed by the
+    Copyright Holder, and derivatives of that collection and/or of
+    those files. A given Package may consist of either the Standard
+    Version, or a Modified Version.
+
+    "Distribute" means providing a copy of the Package or making it
+    accessible to anyone else, or in the case of a company or
+    organization, to others outside of your company or organization.
+
+    "Distributor Fee" means any fee that you charge for Distributing
+    this Package or providing support for this Package to another
+    party.  It does not mean licensing fees.
+
+    "Standard Version" refers to the Package if it has not been
+    modified, or has been modified only in ways explicitly requested
+    by the Copyright Holder.
+
+    "Modified Version" means the Package, if it has been changed, and
+    such changes were not explicitly requested by the Copyright
+    Holder. 
+
+    "Original License" means this Artistic License as Distributed with
+    the Standard Version of the Package, in its current version or as
+    it may be modified by The Perl Foundation in the future.
+
+    "Source" form means the source code, documentation source, and
+    configuration files for the Package.
+
+    "Compiled" form means the compiled bytecode, object code, binary,
+    or any other form resulting from mechanical transformation or
+    translation of the Source form.
+
+
+Permission for Use and Modification Without Distribution
+
+(1)  You are permitted to use the Standard Version and create and use
+Modified Versions for any purpose without restriction, provided that
+you do not Distribute the Modified Version.
+
+
+Permissions for Redistribution of the Standard Version
+
+(2)  You may Distribute verbatim copies of the Source form of the
+Standard Version of this Package in any medium without restriction,
+either gratis or for a Distributor Fee, provided that you duplicate
+all of the original copyright notices and associated disclaimers.  At
+your discretion, such verbatim copies may or may not include a
+Compiled form of the Package.
+
+(3)  You may apply any bug fixes, portability changes, and other
+modifications made available from the Copyright Holder.  The resulting
+Package will still be considered the Standard Version, and as such
+will be subject to the Original License.
+
+
+Distribution of Modified Versions of the Package as Source 
+
+(4)  You may Distribute your Modified Version as Source (either gratis
+or for a Distributor Fee, and with or without a Compiled form of the
+Modified Version) provided that you clearly document how it differs
+from the Standard Version, including, but not limited to, documenting
+any non-standard features, executables, or modules, and provided that
+you do at least ONE of the following:
+
+    (a)  make the Modified Version available to the Copyright Holder
+    of the Standard Version, under the Original License, so that the
+    Copyright Holder may include your modifications in the Standard
+    Version.
+
+    (b)  ensure that installation of your Modified Version does not
+    prevent the user installing or running the Standard Version. In
+    addition, the Modified Version must bear a name that is different
+    from the name of the Standard Version.
+
+    (c)  allow anyone who receives a copy of the Modified Version to
+    make the Source form of the Modified Version available to others
+    under
+		
+	(i)  the Original License or
+
+	(ii)  a license that permits the licensee to freely copy,
+	modify and redistribute the Modified Version using the same
+	licensing terms that apply to the copy that the licensee
+	received, and requires that the Source form of the Modified
+	Version, and of any works derived from it, be made freely
+	available in that license fees are prohibited but Distributor
+	Fees are allowed.
+
+
+Distribution of Compiled Forms of the Standard Version 
+or Modified Versions without the Source
+
+(5)  You may Distribute Compiled forms of the Standard Version without
+the Source, provided that you include complete instructions on how to
+get the Source of the Standard Version.  Such instructions must be
+valid at the time of your distribution.  If these instructions, at any
+time while you are carrying out such distribution, become invalid, you
+must provide new instructions on demand or cease further distribution.
+If you provide valid instructions or cease distribution within thirty
+days after you become aware that the instructions are invalid, then
+you do not forfeit any of your rights under this license.
+
+(6)  You may Distribute a Modified Version in Compiled form without
+the Source, provided that you comply with Section 4 with respect to
+the Source of the Modified Version.
+
+
+Aggregating or Linking the Package 
+
+(7)  You may aggregate the Package (either the Standard Version or
+Modified Version) with other packages and Distribute the resulting
+aggregation provided that you do not charge a licensing fee for the
+Package.  Distributor Fees are permitted, and licensing fees for other
+components in the aggregation are permitted. The terms of this license
+apply to the use and Distribution of the Standard or Modified Versions
+as included in the aggregation.
+
+(8) You are permitted to link Modified and Standard Versions with
+other works, to embed the Package in a larger work of your own, or to
+build stand-alone binary or bytecode versions of applications that
+include the Package, and Distribute the result without restriction,
+provided the result does not expose a direct interface to the Package.
+
+
+Items That are Not Considered Part of a Modified Version 
+
+(9) Works (including, but not limited to, modules and scripts) that
+merely extend or make use of the Package, do not, by themselves, cause
+the Package to be a Modified Version.  In addition, such works are not
+considered parts of the Package itself, and are not subject to the
+terms of this license.
+
+
+General Provisions
+
+(10)  Any use, modification, and distribution of the Standard or
+Modified Versions is governed by this Artistic License. By using,
+modifying or distributing the Package, you accept this license. Do not
+use, modify, or distribute the Package, if you do not accept this
+license.
+
+(11)  If your Modified Version has been derived from a Modified
+Version made by someone other than you, you are nevertheless required
+to ensure that your Modified Version complies with the requirements of
+this license.
+
+(12)  This license does not grant you the right to use any trademark,
+service mark, tradename, or logo of the Copyright Holder.
+
+(13)  This license includes the non-exclusive, worldwide,
+free-of-charge patent license to make, have made, use, offer to sell,
+sell, import and otherwise transfer the Package with respect to any
+patent claims licensable by the Copyright Holder that are necessarily
+infringed by the Package. If you institute patent litigation
+(including a cross-claim or counterclaim) against any party alleging
+that the Package constitutes direct or contributory patent
+infringement, then this Artistic License to you shall terminate on the
+date that such litigation is filed.
+
+(14)  Disclaimer of Warranty:
+THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS
+IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED
+WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR
+NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL
+LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL
+BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF
+ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/vendor/Pod-To-HTML/META6.json

@@ -0,0 +1,20 @@
+{
+    "perl"        : "6.*",
+    "name"        : "Pod::To::HTML",
+    "version"     : "0.4.0",
+    "author" : "Perl 6",
+    "description" : "Convert Perl 6 Pod to HTML",
+    "license"     : "Artistic-2.0",
+    "depends"     : [
+	"URI",
+	"Template::Mustache"
+    ],
+    "test-depends" : ["Test::Output"],
+    "provides"    : {
+        "Pod::To::HTML" : "lib/Pod/To/HTML.pm"
+    },
+    "resources": [
+        "templates/main.mustache"
+    ],
+    "source-url"  : "git://github.com/perl6/Pod-To-HTML.git"
+}

data/vendor/Pod-To-HTML/README.md

@@ -0,0 +1,96 @@
+# Pod::To::HTML
+
+[![Build Status](https://travis-ci.org/perl6/Pod-To-HTML.svg?branch=master)](https://travis-ci.org/perl6/Pod-To-HTML)
+
+Render Perl 6 Pod as HTML
+
+## Install
+
+This module is in the [Perl 6 ecosystem](https://modules.perl6.org), so you install it in the usual way:
+
+    zef install Pod::To::HTML
+
+**Note**: Perl 6 2018.06 introduces changes on how non-breaking
+  whitespace was handled; this is now included in the tests. If
+  the installation fails, please upgrade to Perl 6 >= 2018.06 or
+  simply disregard the test and install with `--force` if that
+  particular feature is of no use to you.
+
+**Note**: Perl6 2018.11 introduced handling of Definition blocks,
+`Defn`. Please upgrade if you are using that feature in the
+documentation.
+
+## SYNOPSIS
+
+From the command line:
+
+    perl6 --doc=HTML lib/FancyModule.pm > FancyModule.html
+
+From within Perl 6:
+
+```perl6
+# Pod Block
+=pod My I<super B<awesome>> embedded C<pod> document!
+
+say Pod::To::HTML.render($=pod[0]);
+
+# Pod file
+say Pod::To::HTML.render('your/file.pod'.IO, header =>
+                         "your-custom-header-inside-body", footer =>
+                         "your-custom-footer-inside-body", head-fields
+                         => "tags-inside-head", lang => "document
+                         language (defaults to 'en')", default-title =
+                         'No =title was found so we use this', css-url
+                         => 'https://example.com/css.css'); # specify
+                         css-url as empty string to disable CSS
+                         inclusion
+
+# Pod string
+
+my $pod = q:to/END/;
+=pod
+My I<super B<awesome>> embedded C<pod>
+document!
+END
+say Pod::To::HTML.render($pod,
+    header =>"your-custom-header-inside-body",
+    footer => "your-custom-footer-inside-body",
+	head-fields => "tags-inside-head",
+    lang => "document language (defaults to 'en')",
+	default-title => 'No =title was found so we use this');
+
+# If you want to use a specific template 
+say pod2html $=pod[0], :templates("lib/templates");
+# main.mustache should be in that directory
+
+
+```
+## DESCRIPTION
+
+`Pod::To::HTML` takes a Pod 6 tree and outputs correspondingly
+formatted HTML. Generally this is done via the command line,
+using`perl6 --doc=HTML`, which extracts the pod from the document and
+feeds it to `Pod::To::HTML`. The other route is with the `render`
+method (called by `--doc=HTML`), which creates a complete HTML
+document from the Pod tree it is called with.
+
+Optionally, a custom header/fooder/head-fields can be
+provided. These can be used to link to custom CSS stylesheets and
+JavaScript libraries.
+
+## Examples
+
+Check the [`examples`](resources/examples/README.md) directory (which should have been installed with your distribution, or is right here if you download from source) for a few illustrative examples.
+
+## DEBUGGING
+
+You can set the `P6DOC_DEBUG` environmental variable to make the
+module produce some debugging information. 
+
+
+## LICENSE
+
+You can use and distribute this module under the terms of the The Artistic License 2.0. See the LICENSE file included in this distribution for complete details.
+
+The META6.json file of this distribution may be distributed and modified without restrictions or attribution.
+

data/vendor/Pod-To-HTML/README.pod6

@@ -0,0 +1,42 @@
+=begin pod
+=TITLE Pod::To::HTML
+
+Render Pod6 as HTML
+
+=begin SYNOPSIS
+
+Use it integrated with Perl 6 documentation system
+
+    perl6 --doc=HTML lib/FancyModule.pm > FancyModule.html
+
+Or as an external function to render your documentation
+
+=begin code
+=pod My I<super B<awesome>> embedded C<pod>  document!
+
+say Pod::To::HTML.render($=pod[0]);
+=end code
+
+=end SYNOPSIS
+
+=begin DESCRIPTION
+
+B<C<Pod::To::HTML>> takes a C<Pod> tree and outputs correspondingly
+formatted C<HTML>. Generally this is via C<perl6 --doc=HTML>, which
+extracts the pod from the document and feeds it to C<Pod::To::HTML>. The
+other route is with the C<render> method (called by C<--doc=HTML>),
+which creates a complete C<HTML> document from the C<Pod> tree it is
+called with.
+
+=end DESCRIPTION
+
+
+=begin LICENSE
+
+You can use and distribute this module under the terms of the The Artistic License 2.0. See the LICENSE file included in this distribution for complete details.
+
+The META6.json file of this distribution may be distributed and modified without restrictions or attribution.
+
+=end LICENSE
+
+=end pod

data/vendor/Pod-To-HTML/TODO

@@ -0,0 +1,5 @@
+* Tests
+    * More of 'em
+    * A cleaner way to test than ms[[ ]];
+* Nested items
+* Generate HTML fragments from Pod fragments better

data/vendor/Pod-To-HTML/lib/Pod/To/HTML.pm

@@ -0,0 +1,691 @@
+unit class Pod::To::HTML;
+use URI::Escape;
+use Template::Mustache;
+
+#try require Term::ANSIColor <&colored>;
+#if &colored.defined {
+    #&colored = -> $t, $c { $t };
+#}
+
+sub colored($text, $how) {
+    $text
+}
+
+multi method render($pod) {
+    pod2html($pod)
+}
+
+multi method render(Array $pod, Str :$header = '', Str :$footer = '', Str :head-fields($head) = '', :$default-title = '', :$lang = 'en') {
+    pod2html($pod, :$header, :$footer, :$head, :$default-title, :$lang)
+}
+
+multi method render(Pod::Block $pod, Str :$header = '', Str :$footer = '', Str :head-fields($head) = '', :$default-title = '', :$lang = 'en') {
+    pod2html($pod, :$header, :$footer, :$head, :$default-title, :$lang)
+}
+
+multi method render(IO::Path $file, Str :$header = '', Str :$footer = '', Str :head-fields($head) = '', :$default-title = '', :$lang = 'en') {
+    use MONKEY-SEE-NO-EVAL;
+    pod2html(EVAL($file.slurp ~ "\n\$=pod"), :$header, :$footer, :$head, :$default-title, :$lang);
+}
+
+multi method render(Str $pod-string, Str :$header = '', Str :$footer = '', Str :head-fields($head) = '', :$default-title = '', :$lang = 'en') {
+    use MONKEY-SEE-NO-EVAL;
+    pod2html(EVAL($pod-string ~ "\n\$=pod"), :$header, :$footer, :$head, :$default-title, :$lang);
+}
+
+# FIXME: this code's a horrible mess. It'd be really helpful to have a module providing a generic
+# way to walk a Pod tree and invoke callbacks on each node, that would reduce the multispaghetti at
+# the bottom to something much more readable.
+
+my &url = {$_};
+my $title;
+my $subtitle;
+my @meta;
+my @indexes;
+my @body;
+my @footnotes;
+my %crossrefs;
+
+# see <https://docs.perl6.org/language/traps#Constants_are_Compile_Time>
+my  $DEBUG := %*ENV<P6DOC_DEBUG>;
+
+sub Debug(Callable $c) { $c() if $DEBUG; }
+
+sub escape_html(Str $str --> Str ) {
+  return $str unless ( $str ~~ /<[ & < > " ' {   ]>/ ) or ( $str ~~ / ' ' / );
+  $str.trans( [ q{&},     q{<},    q{>},    q{"},      q{'},     q{ }     ] =>
+                [ q{&amp;}, q{&lt;}, q{&gt;}, q{&quot;}, q{&#39;}, q{&nbsp;}]);
+}
+
+sub unescape_html(Str $str --> Str ) {
+    $str.trans( [ rx{'&amp;'}, rx{'&lt;'}, rx{'&gt;'}, rx{'&quot;'}, rx{'&#39;'} ] =>
+                [ q{&},        q{<},       q{>},       q{"},         q{'}        ] );
+}
+
+sub escape_id ($id) {
+    $id.trim.subst(/\s+/, '_', :g)
+      .subst('"', '&quot;', :g)
+      .subst('&nbsp;', '_', :g)
+      .subst('&#39;', "'", :g);
+}
+
+multi visit(Nil, |a) {
+    Debug { note colored("visit called for Nil", "bold") }
+}
+
+multi visit($root, :&pre, :&post, :&assemble = -> *% { Nil }) {
+    Debug { note colored("visit called for ", "bold") ~ $root.perl }
+    my ($pre, $post);
+    $pre = pre($root) if defined &pre;
+
+    my @content = $root.?contents.map: {visit $_, :&pre, :&post, :&assemble};
+    $post = post($root, :@content) if defined &post;
+
+    return assemble(:$pre, :$post, :@content, :node($root));
+}
+
+class Pod::List is Pod::Block { };
+class Pod::DefnList is Pod::Block { };
+BEGIN { if ::('Pod::Defn') ~~ Failure { CORE::Pod::<Defn> := class {} } }
+
+sub assemble-list-items(:@content, :$node, *% ) {
+    my @newcont;
+    my $foundone = False;
+    my $everwarn = False;
+
+    my $atlevel = 0;
+    my @pushalias;
+
+    my sub oodwarn($got, $want) {
+        unless $everwarn {
+            warn "=item$got without preceding =item$want found!";
+            $everwarn = True;
+        }
+    }
+
+    for @content {
+        when Pod::Item {
+            $foundone = True;
+
+            # here we deal with @newcont being empty (first list), or with the
+            # last element not being a list (new list)
+            unless +@newcont && @newcont[*-1] ~~ Pod::List {
+                @newcont.push(Pod::List.new());
+                if $_.level > 1 {
+                    oodwarn($_.level, 1);
+                }
+            }
+
+            # only bother doing the binding business if we're at a different
+            # level than previous items
+            if $_.level != $atlevel {
+                # guaranteed to be bound to a Pod::List (see above 'unless')
+                @pushalias := @newcont[*-1].contents;
+
+                for 2..($_.level) -> $L {
+                    unless +@pushalias && @pushalias[*-1] ~~ Pod::List {
+                        @pushalias.push(Pod::List.new());
+                        if +@pushalias == 1 { # we had to push a sublist to a list with no =items
+                            oodwarn($OUTER::_.level, $L);
+                        }
+                    }
+                    @pushalias := @pushalias[*-1].contents;
+                }
+
+                $atlevel = $_.level;
+            }
+
+            @pushalias.push($_);
+        }
+        # This is simpler than lists because we don't need to
+        # list
+        when Pod::Defn {
+            $foundone = True;
+            unless +@newcont && @newcont[*-1] ~~ Pod::DefnList {
+                @newcont.push(Pod::DefnList.new());
+            }
+            @newcont[*-1].contents.push($_);
+        }
+
+        default {
+            @newcont.push($_);
+            $atlevel = 0;
+        }
+    }
+
+    return $foundone ?? $node.clone(contents => @newcont) !! $node;
+}
+
+
+#| Converts a Pod tree to a HTML document using templates
+sub pod2html(
+    $pod,
+    :&url = -> $url { $url },
+    :$head = '',
+    :$header = '',
+    :$footer = '',
+    :$default-title,
+    :$css-url = '//design.perl6.org/perl.css',
+    :$templates = Str,
+    :$lang = 'en'
+    --> Str ) is export {
+
+    my $template-file = %?RESOURCES<templates/main.mustache>;
+    with $templates {
+         if  "$templates/main.mustache".IO ~~ :f {
+             $template-file = "$templates/main.mustache".IO
+         }
+         else {
+            note "$templates does not contain required templates. Using default.";
+        }
+    }
+    ($title, $subtitle, @meta, @indexes, @body, @footnotes) = ();
+    #| Keep count of how many footnotes we've output.
+    my Int $*done-notes = 0;
+    &OUTER::url = &url;
+    @body.push: node2html($pod.map: { visit $_, :assemble(&assemble-list-items) });
+    my $title_html = $title // $default-title // '';
+
+    my Template::Mustache $main-tm .= new;
+    return $main-tm.render( $template-file.IO.slurp, :literal, (
+        :$lang,
+        :title($title_html),
+        :$subtitle,
+        :css($css-url),
+        :meta( do-metadata ),
+        :$head,
+        :toc( do-toc($pod) ),
+        :$header,
+        :@body,
+        :footnotes( do-footnotes ),
+        :$footer).hash
+    );
+
+=comment out
+    my $prelude = qq:to/END/;
+        <!doctype html>
+        <html lang="$lang">
+        <head>
+          <title>{ $title_html }</title>
+          <meta charset="UTF-8" />
+          <style>
+            /* code gets the browser-default font
+             * kbd gets a slightly less common monospace font
+             * samp gets the hard pixelly fonts
+             */
+            kbd \{ font-family: "Droid Sans Mono", "Luxi Mono", "Inconsolata", monospace }
+            samp \{ font-family: "Terminus", "Courier", "Lucida Console", monospace }
+            /* WHATWG HTML frowns on the use of <u> because it looks like a link,
+             * so we make it not look like one.
+             */
+            u \{ text-decoration: none }
+            .nested \{
+                margin-left: 3em;
+            }
+            // footnote things:
+            aside, u \{ opacity: 0.7 }
+            a[id^="fn-"]:target \{ background: #ff0 }
+          </style>
+          { qq|<link rel="stylesheet" href="$css-url">| if $css-url }
+          { do-metadata() // () }
+          $head
+        </head>
+        <body class="pod">
+        <div id="___top"></div>
+        $header
+        END
+=comment out
+    return join(qq{\n},
+        $prelude,
+        ( $title.defined ?? "<h1 class='title'>{$title_html}</h1>"
+                         !! () ),
+        ( $subtitle.defined  ?? "<p class='subtitle'>{$subtitle}</p>"
+                         !! () ),
+        ( my $ToC := do-toc($pod) // () ),
+        '<div class="pod-body', ($ToC ?? '' !! ' no-toc'), '">',@body,'</div>',
+        do-footnotes(),
+        $footer,
+        '</body>',
+        "</html>\n"
+    );
+
+}
+
+#| Returns accumulated metadata as a string of C«<meta>» tags
+sub do-metadata(  --> Str ) {
+    return +@meta ?? '' !! @meta.map(-> $p {
+        qq[<meta name="{escape_html($p.key)}" value="{node2text($p.value)}" />]
+    }).join("\n");
+}
+
+#| Turns accumulated headings into a nested-C«<ol>» table of contents
+sub do-toc($pod --> Str ) {
+    my @levels is default(0) = 0;
+
+    my proto sub find-headings($node, :$inside-heading){*}
+
+    multi sub find-headings(Str $s is raw, :$inside-heading){
+      $inside-heading ?? $s.trim.&escape_html !! ''
+    }
+
+    multi sub find-headings(Pod::FormattingCode $node is raw where *.type eq 'C', :$inside-heading){
+      my $html = $node.contents.map(*.&find-headings(:$inside-heading));
+      $inside-heading ?? qq[<code class="pod-code-inline">{$html}</code>] !! ''
+    }
+
+    multi sub find-headings(Pod::Heading $node is raw, :$inside-heading) {
+      @levels.splice($node.level) if $node.level < +@levels;
+      @levels[$node.level-1]++;
+        my $level-hierarchy = @levels.join('.'); # e.g. §4.2.12
+        my $text = $node.contents.map(*.&find-headings(inside-heading => True));
+        my $link = escape_id(node2text($node.contents));
+        qq[<tr class="toc-level-{$node.level}"><td class="toc-number">{$level-hierarchy}</td><td class="toc-text"><a href="#$link">{$text}</a></td></tr>\n];
+    }
+
+    multi sub find-headings(Positional \list, :$inside-heading){
+        list.map(*.&find-headings(:$inside-heading))
+    }
+
+    multi sub find-headings(Pod::Block $node is raw, :$inside-heading){
+        $node.contents.map(*.&find-headings(:$inside-heading))
+    }
+
+    multi sub find-headings(Pod::Config $node, :$inside-heading){
+        ''
+    }
+
+    multi sub find-headings(Pod::Raw $node is raw, :$inside-heading){
+        $node.contents.map(*.&find-headings(:$inside-heading))
+    }
+
+    my $html = find-headings($pod);
+    $html.trim ??
+        qq:to/EOH/
+        <nav class="indexgroup">
+        <table id="TOC">
+        <caption><h2 id="TOC_Title">Table of Contents</h2></caption>
+        {$html}
+        </table>
+        </nav>
+        EOH
+    !! ''
+}
+
+#| Flushes accumulated footnotes since last call. The idea here is that we can stick calls to this
+#| before each C«</section>» tag (once we have those per-header) and have notes that are visually
+#| and semantically attached to the section.
+sub do-footnotes(  --> Str ) {
+    return '' unless @footnotes;
+
+    my Int $current-note = $*done-notes + 1;
+    my $notes = @footnotes.kv.map(-> $k, $v {
+                    my $num = $k + $current-note;
+                    qq{<li><a href="#fn-ref-$num" id="fn-$num">[↑]</a> $v </li>\n}
+                }).join;
+
+    $*done-notes += @footnotes;
+    @footnotes = ();
+
+    return qq[<aside><ol start="$current-note">\n]
+         ~ $notes
+         ~ qq[</ol></aside>\n];
+}
+
+#| block level or below
+proto sub node2html(| --> Str ) is export {*}
+multi sub node2html($node) {
+    Debug { note colored("Generic node2html called for ", "bold") ~ $node.perl };
+    return node2inline($node);
+}
+
+multi sub node2html(Pod::Block::Declarator $node) {
+    given $node.WHEREFORE {
+        when Routine {
+            "<article>\n"
+                ~ '<code class="pod-code-inline">'
+                    ~ node2text($node.WHEREFORE.name ~ $node.WHEREFORE.signature.perl)
+                ~ "</code>:\n"
+                ~ node2html($node.contents)
+            ~ "\n</article>\n";
+        }
+        default {
+            Debug { note "I don't know what {$node.WHEREFORE.WHAT.perl} is. Assuming class..." };
+        "<h1>"~ node2html([$node.WHEREFORE.perl, q{: }, $node.contents])~ "</h1>";
+        }
+    }
+}
+
+multi sub node2html(Pod::Block::Code $node) {
+    Debug { note colored("Code node2html called for ", "bold") ~ $node.gist };
+    if %*POD2HTML-CALLBACKS and %*POD2HTML-CALLBACKS<code> -> &cb {
+        return cb :$node, default => sub ($node) {
+            return '<pre class="pod-block-code">' ~ node2inline($node.contents) ~ "</pre>\n"
+        }
+    }
+    else  {
+        return '<pre class="pod-block-code">' ~ node2inline($node.contents) ~ "</pre>\n"
+    }
+
+}
+
+multi sub node2html(Pod::Block::Comment $node) {
+    Debug { note colored("Comment node2html called for ", "bold") ~ $node.gist };
+    return '';
+}
+
+multi sub node2html(Pod::Block::Named $node) {
+    Debug { note colored("Named Block node2html called for ", "bold") ~ $node.gist };
+    given $node.name {
+        when 'config' { return '' }
+        when 'nested' {
+            return qq{<div class="nested">\n} ~ node2html($node.contents) ~ qq{\n</div>\n};
+        }
+        when 'output' { return qq[<pre class="pod-block-named-outout">\n] ~ node2inline($node.contents) ~ "</pre>\n"; }
+        when 'pod'  {
+            return qq[<span class="{$node.config<class>}">\n{node2html($node.contents)}</span>\n]
+                if $node.config<class>;
+            return node2html($node.contents);
+        }
+        when 'para' { return node2html($node.contents[0]); }
+        when 'Image' {
+            my $url;
+            if $node.contents == 1 {
+                my $n = $node.contents[0];
+                if $n ~~ Str {
+                    $url = $n;
+                }
+                elsif ($n ~~ Pod::Block::Para) &&  $n.contents == 1 {
+                    $url = $n.contents[0] if $n.contents[0] ~~ Str;
+                }
+            }
+            unless $url.defined {
+                die "Found an Image block, but don't know how to extract the image URL :(";
+            }
+            return qq[<img src="$url" />];
+        }
+        when 'Xhtml' | 'Html' {
+            unescape_html node2rawhtml $node.contents
+        }
+        default {
+            if $node.name eq 'TITLE' {
+                $title = node2text($node.contents);
+                return '';
+            }
+            if $node.name eq 'SUBTITLE' {
+                $subtitle = node2text($node.contents);
+                return '';
+            }
+            elsif $node.name ~~ any(<VERSION DESCRIPTION AUTHOR COPYRIGHT SUMMARY>)
+              and $node.contents[0] ~~ Pod::Block::Para {
+                @meta.push: Pair.new(
+                    key => $node.name.lc,
+                    value => $node.contents
+                );
+            }
+
+            return '<section>'
+                ~ "<h1>{$node.name}</h1>\n"
+                ~ node2html($node.contents)
+                ~ "</section>\n";
+        }
+    }
+}
+
+sub node2rawhtml(Positional $node) {
+    return $node.map({ node2rawtext $_ }).join
+}
+
+multi sub node2html(Pod::Block::Para $node) {
+    Debug { note colored("Para node2html called for ", "bold") ~ $node.gist };
+    return '<p>' ~ node2inline($node.contents) ~ "</p>\n";
+}
+
+multi sub node2html(Pod::Block::Table $node) {
+    Debug { note colored("Table node2html called for ", "bold") ~ $node.gist };
+    my @r = $node.config<class>??'<table class="pod-table '~$node.config<class>~'">'!!'<table class="pod-table">';
+
+    if $node.caption -> $c {
+        @r.push("<caption>{node2inline($c)}</caption>");
+    }
+
+    if $node.headers {
+        @r.push(
+            '<thead><tr>',
+            $node.headers.map(-> $cell {
+                "<th>{node2html($cell)}</th>"
+            }),
+            '</tr></thead>'
+        );
+    }
+
+    @r.push(
+        '<tbody>',
+        $node.contents.map(-> $line {
+            '<tr>',
+            $line.list.map(-> $cell {
+                "<td>{node2html($cell)}</td>"
+            }),
+            '</tr>'
+        }),
+        '</tbody>',
+        '</table>'
+    );
+
+    return @r.join("\n");
+}
+
+multi sub node2html(Pod::Config $node) {
+    Debug { note colored("Config node2html called for ", "bold") ~ $node.perl };
+    return '';
+}
+
+multi sub node2html(Pod::DefnList $node ) {
+    return "<dl>\n" ~ node2html($node.contents) ~ "\n</dl>\n";
+
+}
+multi sub node2html(Pod::Defn $node) {
+
+                    "<dt>" ~ node2html($node.term) ~ "</dt>\n" ~
+                    "<dd>" ~ node2html($node.contents) ~ "</dd>\n";
+}
+
+# TODO: would like some way to wrap these and the following content in a <section>; this might be
+# the same way we get lists working...
+multi sub node2html(Pod::Heading $node) {
+    Debug { note colored("Heading node2html called for ", "bold") ~ $node.gist };
+    my $lvl = min($node.level, 6); #= HTML only has 6 levels of numbered headings
+    my %escaped = (
+        id => escape_id(node2rawtext($node.contents)),
+        html => node2inline($node.contents),
+    );
+
+    %escaped<uri> = uri_escape %escaped<id>;
+
+    @indexes.push: Pair.new(key => $lvl, value => %escaped);
+
+    my $content;
+    if ( %escaped<html> ~~ m{href .+ \<\/a\>} ) {
+      $content =  %escaped<html>;
+    } else {
+      $content = qq[<a class="u" href="#___top" title="go to top of document">]
+    ~ %escaped<html>
+    ~ qq[</a>];
+    }
+
+    return sprintf('<h%d id="%s">', $lvl, %escaped<id>)
+                ~ $content ~ qq[</h{$lvl}>\n];
+}
+
+# FIXME
+multi sub node2html(Pod::List $node) {
+    return '<ul>' ~ node2html($node.contents) ~ "</ul>\n";
+}
+multi sub node2html(Pod::Item $node) {
+    Debug { note colored("List Item node2html called for ", "bold") ~ $node.gist };
+    return '<li>' ~ node2html($node.contents) ~ "</li>\n";
+}
+
+multi sub node2html(Positional $node) {
+    return $node.map({ node2html($_) }).join
+}
+
+multi sub node2html(Str $node) {
+    return escape_html($node);
+}
+
+
+#| inline level or below
+multi sub node2inline($node --> Str ) {
+  Debug { note colored("missing a node2inline multi for ", "bold") ~ $node.gist };
+  return node2text($node);
+}
+
+multi sub node2inline(Pod::Block::Para $node --> Str ) {
+  return node2inline($node.contents);
+}
+
+multi sub node2inline(Pod::FormattingCode $node --> Str ) {
+    my %basic-html = (
+        B => 'strong',  #= Basis
+        C => 'code',    #= Code
+        I => 'em',      #= Important
+        K => 'kbd',     #= Keyboard
+        R => 'var',     #= Replaceable
+        T => 'samp',    #= Terminal
+        U => 'u',       #= Unusual (css: text-decoration-line: underline)
+    );
+
+    given $node.type {
+        when any(%basic-html.keys) {
+            return q{<} ~ %basic-html{$_} ~ q{>}
+                ~ node2inline($node.contents)
+                ~ q{</} ~ %basic-html{$_} ~ q{>};
+        }
+
+        # Escape
+        when 'E' {
+            return $node.meta.map({
+                when Int { "&#$_;" }
+                when Str { "&$_;"  }
+            }).join;
+        }
+
+        # Note
+        when 'N' {
+            @footnotes.push(node2inline($node.contents));
+
+            my $id = +@footnotes;
+            return qq{<a href="#fn-$id" id="fn-ref-$id">[$id]</a>};
+        }
+
+        # Links
+        when 'L' {
+            my $text = node2inline($node.contents);
+            my $url  = $node.meta[0] || node2text($node.contents);
+            if $text ~~ /^'#'/ {
+                # if we have an internal-only link, strip the # from the text.
+                $text = $/.postmatch
+            }
+            $url = url(unescape_html($url));
+            if $url ~~ /^'#'/ {
+                $url = '#' ~ uri_escape( escape_id($/.postmatch) )
+            }
+            return qq[<a href="$url">{$text}</a>]
+        }
+
+        # zero-width comment
+        when 'Z' {
+            return '';
+        }
+
+        when 'D' {
+            # TODO memorise these definitions (in $node.meta) and display them properly
+            my $text = node2inline($node.contents);
+            return qq[<defn>{$text}</defn>]
+        }
+
+        when 'X' {
+            multi sub recurse-until-str(Str:D $s){ $s }
+            multi sub recurse-until-str(Pod::Block $n){ $n.contents>>.&recurse-until-str().join }
+
+            my $index-text = recurse-until-str($node).join;
+            my @indices = $node.meta;
+            my $index-name-attr = qq[index-entry{@indices ?? '-' !! ''}{@indices.join('-')}{$index-text ?? '-' !! ''}$index-text].subst('_', '__', :g).subst(' ', '_', :g).subst('%', '%25', :g).subst('#', '%23', :g);
+
+            my $text = node2inline($node.contents);
+            %crossrefs{$_} = $text for @indices;
+
+            return qq[<a name="$index-name-attr"><span class="index-entry">$text\</span></a>] if $text;
+            return qq[<a name="$index-name-attr"></a>];
+        }
+
+        # Stuff I haven't figured out yet
+        default {
+            Debug { note colored("missing handling for a formatting code of type ", "red") ~ $node.type }
+            return qq{<kbd class="pod2html-todo">$node.type()&lt;}
+                    ~ node2inline($node.contents)
+                    ~ q{&gt;</kbd>};
+        }
+    }
+}
+
+  multi sub node2inline(Positional $node --> Str ) {
+    return $node.map({ node2inline($_) }).join;
+}
+
+  multi sub node2inline(Str $node --> Str ) {
+    return escape_html($node);
+}
+
+
+#| HTML-escaped text
+multi sub node2text($node --> Str ) {
+    Debug { note colored("missing a node2text multi for ", "red") ~ $node.perl };
+    return escape_html(node2rawtext($node));
+}
+
+multi sub node2text(Pod::Block::Para $node --> Str ) {
+    return node2text($node.contents);
+}
+
+multi sub node2text(Pod::Raw $node --> Str ) {
+    my $t = $node.target;
+    if $t && lc($t) eq 'html' {
+        $node.contents.join
+    }
+    else {
+        '';
+    }
+}
+
+# FIXME: a lot of these multis are identical except the function name used...
+#        there has to be a better way to write this?
+multi sub node2text(Positional $node --> Str ) {
+    return $node.map({ node2text($_) }).join;
+}
+
+multi sub node2text(Str $node --> Str ) {
+    return escape_html($node);
+}
+
+
+#| plain, unescaped text
+multi sub node2rawtext($node --> Str ) {
+    Debug { note colored("Generic node2rawtext called with ", "red") ~ $node.perl };
+    return $node.Str;
+}
+
+multi sub node2rawtext(Pod::Block $node --> Str ) {
+    Debug { note colored("node2rawtext called for ", "bold") ~ $node.gist };
+    return node2rawtext($node.contents);
+}
+
+multi sub node2rawtext(Positional $node --> Str ) {
+    return $node.map({ node2rawtext($_) }).join;
+}
+
+multi sub node2rawtext(Str $node --> Str ) {
+    return $node;
+}
+
+# vim: expandtab shiftwidth=4 ft=perl6