docs: generate HTML from testsuite POD documentation

diff --git a/DEPENDS b/DEPENDS
index 35a03f2593cea5d6c9bc4bfa10ad92c8a22494f8..fe9ba17f9eb66ad960ac734d1d7034ec7059a084 100644 (file)
--- a/DEPENDS
+++ b/DEPENDS
@@ -16,6 +16,7 @@
 │ yajl        │ 1.0.8  │ 2.0.1  │ http://lloyd.github.com/yajl/          │
 │ asciidoc    │ 8.3.0  │ 8.6.4  │ http://www.methods.co.nz/asciidoc/     │
 │ xmlto       │ 0.0.23 │ 0.0.23 │ http://www.methods.co.nz/asciidoc/     │
+│ Pod::Simple²│ 3.22   │ 3.22   │ http://search.cpan.org/~dwheeler/Pod-Simple-3.23/
 │ docbook-xml │ 4.5    │ 4.5    │ http://www.methods.co.nz/asciidoc/     │
 │ libxcursor  │ 1.1.11 │ 1.1.11 │ http://ftp.x.org/pub/current/src/lib/  │
 │ Xlib        │ 1.3.3  │ 1.4.3  │ http://ftp.x.org/pub/current/src/lib/  │
@@ -25,6 +26,8 @@
 │ cairo       │ 1.12.2 │ 1.12.2 │ http://cairographics.org/              │
 └─────────────┴────────┴────────┴────────────────────────────────────────┘
  ¹ libsn = libstartup-notification
+ ² Pod::Simple is a Perl module required for converting the testsuite
+   documentation to HTML. See http://michael.stapelberg.de/cpan/#Pod::Simple
 
  i3bar, i3-msg, i3-input, i3-nagbar and i3-config-wizard do not introduce any
  new dependencies.

diff --git a/common.mk b/common.mk
index 8de425d0aabddb545cf80d6f557814ff60ebdf7f..bb5cf79346b3b9b06265ad7716f81b263b967b43 100644 (file)
--- a/common.mk
+++ b/common.mk
@@ -194,6 +194,7 @@ ifeq ($(V),0)
 
 # echo-ing vars
 V_ASCIIDOC = echo ASCIIDOC $@;
+V_POD2HTML = echo POD2HTML $@;
 V_A2X = echo A2X $@;
 endif
 

diff --git a/debian/control b/debian/control
index 4ec5cbc80be946b7918f59ad1612097252abfc0a..02f00de25f2e7cb13c2d2e2250ba7fb040ec1846 100644 (file)
--- a/debian/control
+++ b/debian/control
@@ -21,7 +21,8 @@ Build-Depends: debhelper (>= 7.0.50~),
                libpcre3-dev,
                libstartup-notification0-dev (>= 0.10),
                libcairo2-dev,
-               libpango1.0-dev
+               libpango1.0-dev,
+               libpod-simple-perl
 Standards-Version: 3.9.3
 Homepage: http://i3wm.org/
 

diff --git a/docs/docs.mk b/docs/docs.mk
index 773c832239703addc9b7f604eaa98ac1e0f40d1b..c0daed64e2b2a9d5747c368cae031a7ed5ce1514 100644 (file)
--- a/docs/docs.mk
+++ b/docs/docs.mk
@@ -2,6 +2,7 @@ DISTCLEAN_TARGETS += clean-docs
 
 # To pass additional parameters for asciidoc
 ASCIIDOC = asciidoc
+I3POD2HTML = ./docs/i3-pod2html
 
 ASCIIDOC_NOTOC_TARGETS = \
        docs/debugging.html \
@@ -23,7 +24,17 @@ ASCIIDOC_TARGETS = \
 ASCIIDOC_CALL = $(V_ASCIIDOC)$(ASCIIDOC) -n $(ASCIIDOC_FLAGS) -o $@ $<
 ASCIIDOC_TOC_CALL = $(V_ASCIIDOC)$(ASCIIDOC) -a toc -n $(ASCIIDOC_FLAGS) -o $@ $<
 
-docs: $(ASCIIDOC_TARGETS)
+POD2HTML_TARGETS = \
+       docs/lib-i3test.html \
+       docs/lib-i3test-test.html
+
+docs/lib-i3test.html: testcases/lib/i3test.pm
+       $(V_POD2HTML)$(I3POD2HTML) $< $@
+
+docs/lib-i3test-test.html: testcases/lib/i3test/Test.pm
+       $(V_POD2HTML)$(I3POD2HTML) $< $@
+
+docs: $(ASCIIDOC_TARGETS) $(POD2HTML_TARGETS)
 
 $(ASCIIDOC_TOC_TARGETS): docs/%.html: docs/%
        $(ASCIIDOC_TOC_CALL)
@@ -32,4 +43,4 @@ $(ASCIIDOC_NOTOC_TARGETS): docs/%.html: docs/%
        $(ASCIIDOC_CALL)
 
 clean-docs:
-       rm -f $(ASCIIDOC_TARGETS)
+       rm -f $(ASCIIDOC_TARGETS) $(POD2HTML_TARGETS)

diff --git a/docs/i3-pod2html b/docs/i3-pod2html
new file mode 100755 (executable)
index 0000000..56a769f
--- /dev/null
+++ b/docs/i3-pod2html
@@ -0,0 +1,90 @@
+#!/usr/bin/env perl
+# vim:ts=4:sw=4:expandtab
+
+use strict;
+use warnings;
+use Pod::Simple::HTML;
+use v5.10;
+
+$Pod::Simple::HTML::Tagmap{'Verbatim'} = '<pre><tt>';
+$Pod::Simple::HTML::Tagmap{'VerbatimFormatted'} = '<pre><tt>';
+$Pod::Simple::HTML::Tagmap{'/Verbatim'} = '</tt></pre>';
+$Pod::Simple::HTML::Tagmap{'/VerbatimFormatted'} = '</tt></pre>';
+
+if (@ARGV < 2) {
+    say STDERR "Syntax: i3-pod2html <pod-input-path> <html-output-path>";
+    exit 1;
+}
+
+open(my $in, '<', $ARGV[0]) or die "Couldn’t open $ARGV[0] for reading: $!\n";
+open(my $out, '>', $ARGV[1]) or die "Couldn’t open $ARGV[1] for writing: $!\n";
+
+my $parser = Pod::Simple::HTML->new();
+
+$parser->index(1);
+$parser->html_header_before_title(
+<<'EOF'
+<!doctype html>
+<html lang="en">
+<head>
+<link rel="icon" type="image/png" href="/favicon.png">
+<meta charset="utf-8">
+<meta name="generator" content="Pod::Simple::HTML">
+<meta name="description" content="i3 Perl documentation (testsuite)">
+<link rel="stylesheet" href="http://i3wm.org/css/style.css" type="text/css" />
+<style type="text/css">
+.pod pre {
+    background: #333;
+    border: 1px solid #555;
+    border-left: 5px solid #555;
+    padding: 0.5em;
+    padding-left: 0;
+    padding-right: 0.5em;
+    white-space: pre;
+    color: white;
+}
+
+.pod ul {
+    list-style-type: none;
+}
+.pod li {
+    margin-bottom: 0 !important;
+}
+
+tt {
+    font-family: 'Droid Sans Mono', sans-serif;
+    font-size: inherit;
+}
+
+.pod h1 a, .pod h2 a, .pod h3 a, .pod h4 a {
+    text-decoration: none;
+    color: white;
+}
+</style>
+<title>
+EOF
+);
+$parser->html_header_after_title(
+<<'EOF'
+</title>
+</head>
+<body>
+
+        <div id="main">
+            <a href="/"><h1 id="title">i3 - improved tiling WM</h1></a>
+                       <ul id="nav">
+                               <li><a style="border-bottom: 2px solid #fff" href="/docs">Docs</a></li>
+                               <li><a href="/screenshots">Screens</a></li>
+                               <li><a href="http://faq.i3wm.org/">FAQ</a></li>
+                               <li><a href="/contact">Contact</a></li>
+                               <li><a href="http://bugs.i3wm.org/">Bugs</a></li>
+                       </ul>
+       <br style="clear: both">
+<div id="content" class="pod">
+<h1>i3 Perl documentation (testsuite)</h1>
+
+EOF
+);
+
+$parser->output_fh($out);
+$parser->parse_file($in);