PODS2HTML(1p)

💅 PODS2HTML — the bestie guide 💅

okay so real talk, this is pods2html(1p) from the User Contributed Perl Documentation corner of the universe, and it's literally the glow-up machine for your POD docs. buckle up 🎀

---

✨ NAME ✨

pods2html — translate a tree of PODs to HTML 🦋

---

🌸 SYNOPSIS 🌸

"pods2html" ["--base" url] ["--css" url] ["--empty"] ["--index" title]
["--module"] ["--"["no"]"toc"] ["--hr" level] ["--bgcolor" #rrggbb]
["--text" #rrggbb] ["--variables" values.pl] PODdir HTMLdir [template
[variable=value ...]]

---

👑 DESCRIPTION 👑

so here's the vibe: pods2html goes hunting through the whole directory tree rooted at PODdir and finds every single .pod and .pm file chilling in there. then it translates each POD into HTML and drops it into a matching parallel directory tree rooted at HTMLdir. it's giving mirror dimension but make it documentation 💖

and bestie, it makes those HTML files world-readable. sharing is caring, periodt.

if you hand it a template file, that template gets filled in by the Text::Template module and written to dest. here's the most minimal template ever, and it shows off every single variable that pods2html sets for you:

<html>
 <head>
  <base href="{$base}">
  <link href="{$css}" rel="stylesheet" type="text/css">
  <title>{$title}</title>
 </head>
 <body bgcolor="{$bgcolor}" text="{$text}">
  {$toc}
  {$body}
 </body>
</html>

now, if you pass the --variables option, then the file values.pl gets executed with a do call before the template is filled in. and values.pl may contain arbitrary Perl code. no cap, arbitrary. the program fragments in the template are evaluated in the Pod::Tree::HTML package, so any variables that values.pl sets in this package will be available to the template. it's a whole little ecosystem 🧚

you can also set additional scalar variables right on the command line using the variable=value syntax. and here's the important bit: variables set on the command line override variables set in values.pl. command line stays winning 💅

---

🌈 OPTIONS 🌈

• --base url — specifies a base URL for HTML links. your links gotta know where home is 🏠
• --css url — specifies a Cascading Style Sheet for the generated HTML pages. and here are example rules for all the different HTML elements that may appear in a POD:

a:link { background: #ff8080 }
body   { background: #f0f0f0 }
code   { background: #c0ffc0 }
dd     { background: #ffffe0 }
dl     { background: #fffff0 }
dt     { background: #ffffc0 }
h1     { background: #ffc0c0 }
h2     { background: #ffe0e0 }
hr     { background: #ff0000; height: 5px }
i      { background: #ffc0c0 }
li     { background: #e0e0e0 }
ol     { background: #fff0ff }
p      { background: #f0f0ff }
pre    { background: #f0fff0 }
ul     { background: #f0ffff }

• --empty — creates HTML files for empty PODs. if you don't pass this option, then no HTML file is created for empty PODs. empty pods stay invisible, as they should 🙈
• --index title — writes an index of all the HTML files to HTMLDir/index.html. title is used as the title of the index page. cute little table of contents energy 📑
• --module — ignores files in directories named t/ and blib/. super useful for translating PODs in a module development directory. bye bye build artifacts 👋
• --["no"]toc — includes or omits the table of contents. default is to include the TOC. yes bestie, the TOC is on by default, you're welcome 💖
• --hr level — controls the profusion of horizontal lines in the output, like so:
  • level 0 — none
  • level 1 — between TOC and body
  • level 2 — after each =head1
  • level 3 — after each =head1 and =head2

default is level 1. so you get exactly one little divider moment unless you ask for more ✨

• --bgcolor #rrggbb — set the background color to #rrggbb. default is white. blank canvas slay 🤍
• --text #rrggbb — set the text color to #rrggbb. default is black. 🖤

---

🫶 REQUIRES 🫶

Pod::Tree::HTML, HTML::Stream

---

💀 BUGS 💀

the recursion check doesn't work on Win32. which means the program will enter an infinite recursion if HTMLdir is a subdirectory of PODdir. like, not me watching this thing eat itself forever 😭 so yeah, don't nest them like that on Win32. consider this your vibe check.

---

⭐ SEE ALSO ⭐

pod2html, Pod::Tree::HTML

---

🌸 AUTHOR 🌸

Steven McDougall, <swmcd@world.std.com>

---

🎀 COPYRIGHT 🎀

Copyright (c) 1999-2010 by Steven McDougall. This program is free software; you can redistribute it and/or modify it under the same terms as Perl.

---

and that's the whole page bestie 🦋 this iconic little manual shipped with perl v5.36.0 and got its timestamp on 2022-11-19, so go forth and translate your PODs, you absolute main character 👑💖