Pod::Thread(3pm)

💖 Pod::Thread — bestie edition 💖

okay so this is Pod::Thread(3pm), a page from the User Contributed Perl Documentation section of your friendly neighbourhood manual, and I'm about to make it make sense. grab a boba, we're doing this 🧋✨

---

✨ NAME ✨

Pod::Thread — the little module that takes your POD and turns it into thread, the HTML macro language. yes bestie, it converts docs. slay.

---

🦋 SYNOPSIS 🦋

look at this gorgeous little code block, no notes:

use Pod::Thread;
my $parser = Pod::Thread->new;

# Read POD from STDIN and write to STDOUT.
$parser->parse_from_filehandle;

# Read POD from file.pod and write to file.th.
$parser->parse_from_file ('file.pod', 'file.th');

three lines and a dream. periodt 💅

---

🌸 DESCRIPTION 🌸

okay so Pod::Thread is a module that converts documentation in the POD format — which is, quote unquote, the preferred language for documenting Perl, and honestly? correct — into thread, which is an HTML macro language. the whole point is that it lets the converter from thread to HTML deal with some of the annoying parts of conversion to HTML. so the HTML side doesn't have to be stressed. it's giving teamwork 🫶

Pod::Thread is primarily intended for use with the DocKnot static site generator (specifically the App::DocKnot::Spin module), which is the thing that actually implements the thread macro language. this module here just does the POD formatting into thread, and thus on into HTML. it's the middle bestie in the group chat 😭

since it's a derived class from Pod::Simple, Pod::Thread supports the same methods and interfaces. briefly — and I do mean briefly, because Pod::Simple has the full tea — you create a new parser with Pod::Thread->new(), set the output destination with either output_fh() or output_string(), and then call one of parse_file(), parse_string_document(), or parse_lines(). go read Pod::Simple for all the details, it's iconic.

and here's the part where new() can take options, in the form of key/value pairs, to control the behavior of the formatter:

• contents — if you set it to a true value, it outputs a table of contents section at the beginning of the document. only top-level headings will be shown, so don't come for it about the subheadings 💀
• navbar — if you set it to a true value, it outputs a navigation bar at the beginning of the document with links to all top-level headings. cute and functional ✨
• style — sets the name of the style sheet to use. if it's not given, no reference to a style sheet will be included in the generated page. no style, no reference, no drama.
• title — the title of the document. if this is set, it will be used rather than looking for and parsing a NAME section in the POD file, and NAME sections will no longer be required or special. you're the main character now 👑

---

😭 DIAGNOSTICS 😭

• Cannot write to output: %s — (F). an error occurred while attempting to write the thread result to the configured output string or file handle. it's a fatal one, bestie, no cap.
• POD document had syntax errors — (F). the POD document being formatted had syntax errors. also fatal. the vibe check failed 🙈

---

💜 AUTHOR 💜

Russ Allbery <rra@cpan.org>, based heavily on Pod::Text from podlators. shoutout, legend behaviour.

---

🎀 COPYRIGHT AND LICENSE 🎀

Copyright 2002, 2008-2009, 2013, 2021 Russ Allbery <rra@cpan.org>

and now the legal bit, which we keep EXACTLY as is because that's how licenses work:

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

yes I typed the whole thing out. every word. do not test me 🫡

---

⭐ SEE ALSO ⭐

• App::DocKnot::Spin
• Pod::Simple
• docknot(1)

this module is part of the Pod-Thread distribution. the current version of Pod-Thread is available from CPAN, or directly from its web site at <https://www.eyrie.org/~eagle/software/pod-thread/>. 🔗

DocKnot is available as the App-DocKnot distribution from CPAN, or directly from its web site at <https://www.eyrie.org/~eagle/software/docknot/>. 🔗

---

and that's the whole page, bestie!! this was Pod::Thread(3pm) as shipped with perl v5.32.1, dated 2021-12-26 — so yeah, it's got a lil vintage moment going on, and we love that for it 🌈💖 go forth and convert your POD. you got this. mwah 🎀