Merge pull request #1 from perl6/master

finanalyst · web-flow · commit 24dd32b08785 · 2018-12-11T11:18:16.000+08:00
update
diff --git a/.gitignore b/.gitignore
@@ -1,2 +1,2 @@
-.precomp/
-
+*~
+.precomp
diff --git a/.travis.yml b/.travis.yml
@@ -5,6 +5,7 @@ language: perl6
 sudo: false
 perl6:
   - latest
+  - '2017.12'
 install:
   - rakudobrew build-zef
   - zef --debug install .
diff --git a/META6.json b/META6.json
@@ -1,10 +1,14 @@
 {
     "perl"        : "6.*",
     "name"        : "Pod::To::HTML",
-    "version"     : "0.3.22",
+    "version"     : "0.4.0",
+    "author" : "Perl 6",
     "description" : "Convert Perl 6 Pod to HTML",
     "license"     : "Artistic-2.0",
-    "depends"     : ["URI", "Template::Mustache"],
+    "depends"     : [
+	"URI",
+	"Template::Mustache"
+    ],
     "test-depends" : ["Test::Output"],
     "provides"    : {
         "Pod::To::HTML" : "lib/Pod/To/HTML.pm"
diff --git a/README.md b/README.md
@@ -16,6 +16,10 @@ This module is in the [Perl 6 ecosystem](https://modules.perl6.org), so you inst
   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:
@@ -55,8 +59,12 @@ say Pod::To::HTML.render($pod,
     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
@@ -70,6 +78,9 @@ 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
 
diff --git a/README.pod6 b/README.pod6
@@ -5,17 +5,17 @@ Render Pod6 as HTML
 
 =begin SYNOPSIS
 
-=item
+Use it integrated with Perl 6 documentation system
+
     perl6 --doc=HTML lib/FancyModule.pm > FancyModule.html
 
-=begin item
-    =begin code
-    =pod My I<super B<awesome>> embedded C<pod>
-    document!
+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 item
+say Pod::To::HTML.render($=pod[0]);
+=end code
 
 =end SYNOPSIS
 
diff --git a/lib/Pod/To/HTML.pm b/lib/Pod/To/HTML.pm
@@ -157,7 +157,7 @@ sub assemble-list-items(:@content, :$node, *% ) {
 }
 
 
-#| Converts a Pod tree to a HTML document.
+#| Converts a Pod tree to a HTML document using templates
 sub pod2html(
     $pod,
     :&url = -> $url { $url },
@@ -171,7 +171,7 @@ sub pod2html(
     --> Str ) is export {
 
     my $template-file = %?RESOURCES<templates/main.mustache>;
-     with $templates {
+    with $templates {
          if  "$templates/main.mustache".IO ~~ :f {
              $template-file = "$templates/main.mustache".IO
          }
diff --git a/resources/examples/01-parse-files.p6 b/resources/examples/01-parse-files.p6
diff --git a/resources/examples/README.md b/resources/examples/README.md
@@ -0,0 +1,13 @@
+# Some examples for the module.
+
+Test
+
+	perl6 -I../../lib render.p6
+
+which uses the local [template `main.mustache`](main.mustache) instead of the default one. Add a pod6 or pm6 file at the end if you want to check a different file. 
+
+Change to the upper dir, and run
+
+	perl6 -Ilib resources/examples/01-parse-files.p6
+
+for a similar version which uses the same file.
diff --git a/resources/examples/main.mustache b/resources/examples/main.mustache
@@ -0,0 +1,26 @@
+<!doctype html>
+<html lang="{{ lang }}">
+  <head>
+    <title>{{ title }}</title>
+    <meta charset="UTF-8" />
+    <style>
+      kbd { font-family: "Droid Sans Mono", "Luxi Mono", "Inconsolata", monospace }
+      samp, code { font-family: "Terminus", "Courier", "Lucida Console", monospace }
+      
+      .nested {
+      margin-left: 3em;
+      }
+      aside, u { opacity: 0.7 }
+        a[id^="fn-"]:target { background: #ff0 }
+        </style>
+  </head>
+  <body class="pod">
+    <div id="___top"></div>
+    {{{ header }}}
+    {{# title }}<h1 class='title'>{{ title }}</h1>{{/ title }}
+    {{# subtitle }}<p class='subtitle'>{{ subtitle }}</p>{{/ subtitle }}
+      <div class="pod-body no-toc">
+    {{# body }}{{{ . }}}{{/ body }}
+      </div>
+    </body>
+</html>
diff --git a/resources/examples/render.p6 b/resources/examples/render.p6
@@ -0,0 +1,17 @@
+#!/usr/bin/env perl6
+
+use v6;
+use MONKEY-SEE-NO-EVAL;
+use Pod::To::HTML;
+
+sub MAIN( $file = "../../README.pod6" ) {
+    my $file-content = $file.IO.slurp;
+    die "No pod here" if not $file-content ~~ /\=begin \s+ pod/;
+    my $pod;
+    try {
+	$pod = EVAL($file-content ~ "\n\$=pod");
+    };
+    die "Pod fails: $!" if $!;
+    my $result = pod2html( $pod, templates => '.' );
+    say $result;
+}
diff --git a/resources/templates/main.mustache b/resources/templates/main.mustache
@@ -15,7 +15,7 @@
         </style>
         {{# css }}<link rel="stylesheet" href="{{ css }}">{{/ css }}
         {{# metadata }}{{{ metadata }}}{{/ metadata }}
-        {{ head }}
+        {{{ head }}}
     </head>
     <body class="pod">
     <div id="___top"></div>
diff --git a/t/075-defn.t b/t/075-defn.t
@@ -24,9 +24,11 @@ Having the quality of general expediency.
 
 =end pod
 
+say $=pod[0].perl;
 
 my $html = pod2html($=pod[0]);
 
+say $html;
 ok $html ~~ ms[[
 '<dl>'
 '<dt>MAD</dt>'
diff --git a/t/120-templates.t b/t/120-templates.t
@@ -1,10 +1,12 @@
-use Test;
+use Test; # -*- mode: perl6 -*- 
 use Test::Output;
 use Pod::To::HTML;
-plan 3;
+plan 5;
 my $r;
 
 =begin pod
+=TITLE The usual suspects
+
 The seven suspects are:
 
 =item  Happy
@@ -32,3 +34,9 @@ ok $r ~~ ms[[
 
 $r = pod2html $=pod[0], :templates("t/templates");
 ok $r ~~ ms[[  '<meta description="This is a new template"/>' ]], 'Gets text from new template';
+ok $r ~~ ms[[ "<h1 class='title'>The usual suspects</h1>" ]], 'Fills template correctly';
+
+my $head='<meta name=viewport content="width=device-width, initial-scale=1">';
+$r = pod2html $=pod[0], :templates("t/templates"), :$head ;
+ok $r ~~ ms[[ $head ]], 'headers are redered as is';
+
diff --git a/t/templates/main.mustache b/t/templates/main.mustache
@@ -16,7 +16,7 @@
         </style>
         {{# css }}<link rel="stylesheet" href="{{ css }}">{{/ css }}
         {{# metadata }}{{{ metadata }}}{{/ metadata }}
-        {{ head }}
+        {{{ head }}}
     </head>
     <body class="pod">
     <div id="___top"></div>

-Original file line number
+Diff line change
@@ @@ -1,2 +1,2 @@ @@
 -.precomp/
+-
 +*~
 +.precomp
Original file line number	Diff line number	Diff line change
`@@ -157,7 +157,7 @@ sub assemble-list-items(:@content, :$node, *% ) {`
`157`	`157`	`}`
`158`	`158`
`159`	`159`
`160`		`-#\| Converts a Pod tree to a HTML document.`
	`160`	`+#\| Converts a Pod tree to a HTML document using templates`
`161`	`161`	`sub pod2html(`
`162`	`162`	`$pod,`
`163`	`163`	`:&url = -> $url { $url },`
`@@ -171,7 +171,7 @@ sub pod2html(`
`171`	`171`	`--> Str ) is export {`
`172`	`172`
`173`	`173`	`my $template-file = %?RESOURCES<templates/main.mustache>;`
`174`		`- with $templates {`
	`174`	`+ with $templates {`
`175`	`175`	`if "$templates/main.mustache".IO ~~ :f {`
`176`	`176`	`$template-file = "$templates/main.mustache".IO`
`177`	`177`	`}`