Skip to content

Commit 5bea7cb

Browse files
stapelbergstapelberg
committed
docs: generate HTML from testsuite POD documentation
1 parent b4afd20 commit 5bea7cb

File tree

5 files changed

+109
-3
lines changed

5 files changed

+109
-3
lines changed

‎DEPENDS

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@
1616
│ yajl │ 1.0.8 │ 2.0.1 │ http://lloyd.github.com/yajl/ │
1717
│ asciidoc │ 8.3.0 │ 8.6.4 │ http://www.methods.co.nz/asciidoc/ │
1818
│ xmlto │ 0.0.23 │ 0.0.23 │ http://www.methods.co.nz/asciidoc/ │
19+
│ Pod::Simple²│ 3.22 │ 3.22 │ http://search.cpan.org/~dwheeler/Pod-Simple-3.23/
1920
│ docbook-xml │ 4.5 │ 4.5 │ http://www.methods.co.nz/asciidoc/ │
2021
│ libxcursor │ 1.1.11 │ 1.1.11 │ http://ftp.x.org/pub/current/src/lib/ │
2122
│ Xlib │ 1.3.3 │ 1.4.3 │ http://ftp.x.org/pub/current/src/lib/ │
@@ -25,6 +26,8 @@
2526
│ cairo │ 1.12.2 │ 1.12.2 │ http://cairographics.org/ │
2627
└─────────────┴────────┴────────┴────────────────────────────────────────┘
2728
¹ libsn = libstartup-notification
29+
² Pod::Simple is a Perl module required for converting the testsuite
30+
documentation to HTML. See http://michael.stapelberg.de/cpan/#Pod::Simple
2831

2932
i3bar, i3-msg, i3-input, i3-nagbar and i3-config-wizard do not introduce any
3033
new dependencies.

‎common.mk

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -194,6 +194,7 @@ ifeq ($(V),0)
194194

195195
# echo-ing vars
196196
V_ASCIIDOC = echo ASCIIDOC $@;
197+
V_POD2HTML = echo POD2HTML $@;
197198
V_A2X = echo A2X $@;
198199
endif
199200

‎debian/control

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,8 @@ Build-Depends: debhelper (>= 7.0.50~),
2121
libpcre3-dev,
2222
libstartup-notification0-dev (>= 0.10),
2323
libcairo2-dev,
24-
libpango1.0-dev
24+
libpango1.0-dev,
25+
libpod-simple-perl
2526
Standards-Version: 3.9.3
2627
Homepage: http://i3wm.org/
2728

‎docs/docs.mk

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ DISTCLEAN_TARGETS += clean-docs
22

33
# To pass additional parameters for asciidoc
44
ASCIIDOC = asciidoc
5+
I3POD2HTML = ./docs/i3-pod2html
56

67
ASCIIDOC_NOTOC_TARGETS = \
78
docs/debugging.html \
@@ -23,7 +24,17 @@ ASCIIDOC_TARGETS = \
2324
ASCIIDOC_CALL = $(V_ASCIIDOC)$(ASCIIDOC) -n $(ASCIIDOC_FLAGS) -o $@ $<
2425
ASCIIDOC_TOC_CALL = $(V_ASCIIDOC)$(ASCIIDOC) -a toc -n $(ASCIIDOC_FLAGS) -o $@ $<
2526

26-
docs: $(ASCIIDOC_TARGETS)
27+
POD2HTML_TARGETS = \
28+
docs/lib-i3test.html \
29+
docs/lib-i3test-test.html
30+
31+
docs/lib-i3test.html: testcases/lib/i3test.pm
32+
$(V_POD2HTML)$(I3POD2HTML) $< $@
33+
34+
docs/lib-i3test-test.html: testcases/lib/i3test/Test.pm
35+
$(V_POD2HTML)$(I3POD2HTML) $< $@
36+
37+
docs: $(ASCIIDOC_TARGETS) $(POD2HTML_TARGETS)
2738

2839
$(ASCIIDOC_TOC_TARGETS): docs/%.html: docs/%
2940
$(ASCIIDOC_TOC_CALL)
@@ -32,4 +43,4 @@ $(ASCIIDOC_NOTOC_TARGETS): docs/%.html: docs/%
3243
$(ASCIIDOC_CALL)
3344

3445
clean-docs:
35-
rm -f $(ASCIIDOC_TARGETS)
46+
rm -f $(ASCIIDOC_TARGETS) $(POD2HTML_TARGETS)

‎docs/i3-pod2html

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
#!/usr/bin/env perl
2+
# vim:ts=4:sw=4:expandtab
3+
4+
use strict;
5+
use warnings;
6+
use Pod::Simple::HTML;
7+
use v5.10;
8+
9+
$Pod::Simple::HTML::Tagmap{'Verbatim'} = '<pre><tt>';
10+
$Pod::Simple::HTML::Tagmap{'VerbatimFormatted'} = '<pre><tt>';
11+
$Pod::Simple::HTML::Tagmap{'/Verbatim'} = '</tt></pre>';
12+
$Pod::Simple::HTML::Tagmap{'/VerbatimFormatted'} = '</tt></pre>';
13+
14+
if (@ARGV < 2) {
15+
say STDERR "Syntax: i3-pod2html <pod-input-path> <html-output-path>";
16+
exit 1;
17+
}
18+
19+
open(my $in, '<', $ARGV[0]) or die "Couldn’t open $ARGV[0] for reading: $!\n";
20+
open(my $out, '>', $ARGV[1]) or die "Couldn’t open $ARGV[1] for writing: $!\n";
21+
22+
my $parser = Pod::Simple::HTML->new();
23+
24+
$parser->index(1);
25+
$parser->html_header_before_title(
26+
<<'EOF'
27+
<!doctype html>
28+
<html lang="en">
29+
<head>
30+
<link rel="icon" type="image/png" href="/favicon.png">
31+
<meta charset="utf-8">
32+
<meta name="generator" content="Pod::Simple::HTML">
33+
<meta name="description" content="i3 Perl documentation (testsuite)">
34+
<link rel="stylesheet" href="http://i3wm.org/css/style.css" type="text/css" />
35+
<style type="text/css">
36+
.pod pre {
37+
background: #333;
38+
border: 1px solid #555;
39+
border-left: 5px solid #555;
40+
padding: 0.5em;
41+
padding-left: 0;
42+
padding-right: 0.5em;
43+
white-space: pre;
44+
color: white;
45+
}
46+
47+
.pod ul {
48+
list-style-type: none;
49+
}
50+
.pod li {
51+
margin-bottom: 0 !important;
52+
}
53+
54+
tt {
55+
font-family: 'Droid Sans Mono', sans-serif;
56+
font-size: inherit;
57+
}
58+
59+
.pod h1 a, .pod h2 a, .pod h3 a, .pod h4 a {
60+
text-decoration: none;
61+
color: white;
62+
}
63+
</style>
64+
<title>
65+
EOF
66+
);
67+
$parser->html_header_after_title(
68+
<<'EOF'
69+
</title>
70+
</head>
71+
<body>
72+
73+
<div id="main">
74+
<a href="/"><h1 id="title">i3 - improved tiling WM</h1></a>
75+
<ul id="nav">
76+
<li><a style="border-bottom: 2px solid #fff" href="/docs">Docs</a></li>
77+
<li><a href="/screenshots">Screens</a></li>
78+
<li><a href="http://faq.i3wm.org/">FAQ</a></li>
79+
<li><a href="/contact">Contact</a></li>
80+
<li><a href="http://bugs.i3wm.org/">Bugs</a></li>
81+
</ul>
82+
<br style="clear: both">
83+
<div id="content" class="pod">
84+
<h1>i3 Perl documentation (testsuite)</h1>
85+
86+
EOF
87+
);
88+
89+
$parser->output_fh($out);
90+
$parser->parse_file($in);

0 commit comments

Comments
 (0)