Pod::T...erlDist(3pm)

👑 Pod::Tree::PerlDist(3pm) — the vibe

okay so bestie, we're in the User Contributed Perl Documentation section, manual page Pod::Tree::PerlDist, section 3pm. and what it does is... translate the Perl distribution's docs into HTML. slay. 💅

---

✨ NAME ✨

Pod::Tree::PerlDist — translate Perl distribution documentation to HTML 🦋

---

🌸 SYNOPSIS 🌸

  $perl_map  = Pod::Tree::PerlMap->new;
  $perl_dist = Pod::Tree::PerlDist->new( $perl_dir, $HTML_dir, $perl_map, %opts );

  $perl_dist->scan;
  $perl_dist->index;
  $perl_dist->translate;

  $top = $perl_dist->get_top_entry;

literally that's the whole flow. scan, index, translate, grab the top entry. periodt. ✨

---

💖 DESCRIPTION 💖

Pod::Tree::PerlDist takes the documents chillin' in the Perl distribution and translates them into HTML. we're talking Changes, README, and assorted other files that show up at the top level of the Perl source tree. it's giving "miscellaneous but essential." 🎀

here's the tea on how it handles them:

• files that contain PODs? parsed as PODs, obviously. 👑
• files that don't contain PODs? converted to HTML as preformatted text. no cap.

Pod::Tree::PerlDist also generates and uses an index of the files it finds, so it can construct HTML links. and the bestie part? other modules can use that index too. sharing is caring. 🫶

---

🧚 METHODS 🧚

🌈 $perl_dist = "new" "Pod::Tree::PerlDist" $perl_dir, $HTML_dir, $perl_map, %options

creates and returns a shiny new Pod::Tree::PerlDist object. iconic.

• $perl_dir is the root of the Perl source tree. 🌳
• $HTML_dir is the directory where the HTML files are gonna get written. 📁
• $perl_map maps file names to URLs. 🗺️
• %options get passed through to Pod::Tree::HTML. ✨

🌈 $perl_dist->"scan"

scans the top level of the Perl source tree looking for documentation files. 👀

files that don't generally contain user-level documentation — source files, for example — get ignored. and important: the search does not recurse through subdirectories. top level only, bestie, no going deeper. 🚫

every file that gets located is entered into $perl_map. 💖

🌈 $perl_dist->"index"

generates a top-level index of all the distribution documents, and writes it to HTML_dir"/dist.html". cute little landing page moment. 🎀

🌈 $perl_dist->"translate"

translates each distribution document that scan found into HTML. the HTML pages get written to HTML_dir. 💅

🌈 $perl_dist->"get_top_entry"

returns a hash reference shaped like this:

  { URL         => $URL,
    description => $description }

Pod::Tree::PerlTop uses this to build a top-level index of all the Perl PODs. teamwork makes the dream work. 🫶

---

🔗 LINKING 🔗

Pod::Tree::PerlDist indexes files by their name. so if you wanna link to a file named README.win32, you write:

  L<README.win32>

that's it. that's the whole thing. iykyk. ✨

---

🍓 REQUIRES 🍓

  5.005;
  HTML::Stream;
  Pod::Tree;
  Pod::Tree::HTML;
  Pod::Tree::PerlUtil;

---

💀 EXPORTS 💀

nothing. zero. zilch. the void. 🕳️

---

👀 SEE ALSO 👀

Pod::Tree::HTML, Pod::Tree::PerlMap

---

💜 AUTHOR 💜

Steven McDougall, swmcd@world.std.com

---

⭐ COPYRIGHT ⭐

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

---

and that's the page, bestie 🎀 this was perl v5.36.0, dated 2022-11-19. go forth and translate some docs. mwah. 💅✨